valgen 7.0.1 → 7.0.3

package/README.md

@@ -119,5 +119,5 @@ at the end of the run.
 [downloads-url]: https://npmjs.org/package/valgen
 [ci-test-image]: https://github.com/panates/valgen/actions/workflows/test.yml/badge.svg
 [ci-test-url]: https://github.com/panates/valgen/actions/workflows/test.yml
-[coveralls-image]: https://img.shields.io/coveralls/panates/valgen/master.svg
+[coveralls-image]: https://img.shields.io/coveralls/panates/valgen/dev.svg
 [coveralls-url]: https://coveralls.io/r/panates/valgen

package/constants.js

@@ -1,4 +1,4 @@
-export const version = '7.0.1';
+export const version = '7.0.3';
 export const postValidation = Symbol('postValidation');
 export const preValidation = Symbol('preValidation');
 export const VALIDATE_METADATA = Symbol('VALIDATE_METADATA');

package/core/constants.d.ts

@@ -1,2 +1,13 @@
+/**
+ * Symbol key used to store a {@link Validator}'s underlying
+ * {@link ValidateFunction} on itself. Exported only because it appears in
+ * `Validator`'s type signature; not intended for direct use.
+ * @internal
+ */
 export declare const kValidatorFn: unique symbol;
+/**
+ * Symbol key used to store a {@link Validator}'s construction-time
+ * {@link ValidationOptions} on itself. Not intended for direct use.
+ * @internal
+ */
 export declare const kOptions: unique symbol;

package/core/constants.js

@@ -1,2 +1,13 @@
+/**
+ * Symbol key used to store a {@link Validator}'s underlying
+ * {@link ValidateFunction} on itself. Exported only because it appears in
+ * `Validator`'s type signature; not intended for direct use.
+ * @internal
+ */
 export const kValidatorFn = Symbol.for('kValidatorFn');
+/**
+ * Symbol key used to store a {@link Validator}'s construction-time
+ * {@link ValidationOptions} on itself. Not intended for direct use.
+ * @internal
+ */
 export const kOptions = Symbol.for('kOptions');

package/core/context.d.ts

@@ -1,20 +1,77 @@
 import type { ErrorIssue, ExecutionOptions, OnFailFunction } from './types.js';
 import type { Validator } from './validator.js';
+/**
+ * Carries execution options and accumulated failures through a single
+ * validation run, including across nested validator calls.
+ *
+ * A root `Context` is created once for a top-level `validator(...)` call;
+ * nested rules (properties of an `isObject` schema, items of an `isArray`,
+ * steps of a `pipe`, ...) share it via {@link Context.extend}, so failures
+ * from anywhere in the run accumulate into the same `errors` array and are
+ * thrown together as a single {@link ValidationError}.
+ */
 export declare class Context implements ExecutionOptions {
+    /** `true` for the context created at the top-level call; `false` for every context produced by {@link Context.extend}. */
     isRoot: boolean;
+    /** Issues recorded so far during this validation run (shared across nested contexts). */
     errors: ErrorIssue[];
+    /** Stops collecting further issues (and throws immediately) once this many have been recorded. */
     maxErrors?: number;
+    /** Intercepts every failure recorded through this context. */
     onFail?: OnFailFunction;
+    /** Enables coercion for rules that support it. */
     coerce?: boolean;
+    /** An identifying name for the root value being validated (e.g. a schema's class name), set once and inherited by every nested context. */
     root?: string;
+    /** A dotted/bracketed path to the value currently being validated, e.g. `"user.address"` or `"items[0]"`. */
     location?: string;
+    /** The object a nested property/item belongs to - used by rules like `exists` to look up property descriptors. */
     scope?: object;
+    /** A human-readable name for the object/schema the current value belongs to. */
     context?: string;
+    /** The name of the property currently being validated, when nested inside an object schema. */
     property?: string;
+    /** The index of the item currently being validated, when nested inside an array/tuple. */
     index?: number;
+    /** A human-readable label for the current value, used to resolve `{{label}}` in message templates. */
     label?: string;
     [key: string]: any;
+    /**
+     * @param options - Initial execution options, assigned directly onto the new context.
+     */
     constructor(options?: ExecutionOptions);
+    /**
+     * Records a validation failure as an {@link ErrorIssue}.
+     *
+     * Resolves `{{key}}` / `{{key|fallback}}` placeholders in `message` against
+     * the issue's own fields (falling back to this context's `location`/
+     * `property` for `{{label}}`), runs the context's `onFail` interceptor if
+     * set, then appends the result to `errors`. Throws immediately once
+     * `errors.length` reaches `maxErrors`; otherwise the root call throws a
+     * single {@link ValidationError} once the whole run completes.
+     *
+     * @param rule - The validator reporting the failure; its `id` is recorded on the issue.
+     * @param message - The failure message, or an `Error` whose `.message` is
+     *   used instead. May contain `{{key}}`/`{{key|fallback}}` placeholders.
+     * @param value - The offending value.
+     * @param details - Additional fields to merge onto the recorded issue.
+     */
     fail(rule: Validator, message: string | Error, value: any, details?: Record<string, any>): void;
+    /**
+     * Creates a child context for a nested validator call, inheriting every
+     * field from this context via the prototype chain and overriding it with
+     * `options` where given.
+     *
+     * Nested rules (an object schema's properties, an array's items, a pipe's
+     * steps, ...) should reuse the *same* extended context across every call
+     * within one loop rather than calling `extend()` per call, and should
+     * prefer the 3-argument form `nestedRule(input, undefined, context)` so
+     * the validator wrapper doesn't extend the context a second time.
+     *
+     * @param options - Fields to override on the child context; `undefined`
+     *   values are skipped so they fall through to the parent instead of
+     *   shadowing it.
+     * @returns A new `Context` with `isRoot: false`, prototypically inheriting from this one.
+     */
     extend(options?: ExecutionOptions): Context;
 }

package/core/context.js

@@ -2,22 +2,63 @@ import { omitUndefined } from '../helpers/omit-undefined.js';
 import { ValidationError } from './validation-error.js';
 const VARIABLE_REPLACE_PATTERN = /{{([^}]*)}}/g;
 const OPTIONAL_VAR_PATTERN = /^([^|]+)(?:\|(.*))?$/;
+/**
+ * Carries execution options and accumulated failures through a single
+ * validation run, including across nested validator calls.
+ *
+ * A root `Context` is created once for a top-level `validator(...)` call;
+ * nested rules (properties of an `isObject` schema, items of an `isArray`,
+ * steps of a `pipe`, ...) share it via {@link Context.extend}, so failures
+ * from anywhere in the run accumulate into the same `errors` array and are
+ * thrown together as a single {@link ValidationError}.
+ */
 export class Context {
+    /** `true` for the context created at the top-level call; `false` for every context produced by {@link Context.extend}. */
     isRoot = true;
+    /** Issues recorded so far during this validation run (shared across nested contexts). */
     errors = [];
+    /** Stops collecting further issues (and throws immediately) once this many have been recorded. */
     maxErrors;
+    /** Intercepts every failure recorded through this context. */
     onFail;
+    /** Enables coercion for rules that support it. */
     coerce;
+    /** An identifying name for the root value being validated (e.g. a schema's class name), set once and inherited by every nested context. */
     root;
+    /** A dotted/bracketed path to the value currently being validated, e.g. `"user.address"` or `"items[0]"`. */
     location;
+    /** The object a nested property/item belongs to - used by rules like `exists` to look up property descriptors. */
     scope;
+    /** A human-readable name for the object/schema the current value belongs to. */
     context;
+    /** The name of the property currently being validated, when nested inside an object schema. */
     property;
+    /** The index of the item currently being validated, when nested inside an array/tuple. */
     index;
+    /** A human-readable label for the current value, used to resolve `{{label}}` in message templates. */
     label;
+    /**
+     * @param options - Initial execution options, assigned directly onto the new context.
+     */
     constructor(options) {
         Object.assign(this, options);
     }
+    /**
+     * Records a validation failure as an {@link ErrorIssue}.
+     *
+     * Resolves `{{key}}` / `{{key|fallback}}` placeholders in `message` against
+     * the issue's own fields (falling back to this context's `location`/
+     * `property` for `{{label}}`), runs the context's `onFail` interceptor if
+     * set, then appends the result to `errors`. Throws immediately once
+     * `errors.length` reaches `maxErrors`; otherwise the root call throws a
+     * single {@link ValidationError} once the whole run completes.
+     *
+     * @param rule - The validator reporting the failure; its `id` is recorded on the issue.
+     * @param message - The failure message, or an `Error` whose `.message` is
+     *   used instead. May contain `{{key}}`/`{{key|fallback}}` placeholders.
+     * @param value - The offending value.
+     * @param details - Additional fields to merge onto the recorded issue.
+     */
     fail(rule, message, value, details) {
         const issue = omitUndefined({
             message: message instanceof Error ? message.message : String(message),
@@ -65,6 +106,22 @@ export class Context {
             throw new ValidationError(this.errors);
         }
     }
+    /**
+     * Creates a child context for a nested validator call, inheriting every
+     * field from this context via the prototype chain and overriding it with
+     * `options` where given.
+     *
+     * Nested rules (an object schema's properties, an array's items, a pipe's
+     * steps, ...) should reuse the *same* extended context across every call
+     * within one loop rather than calling `extend()` per call, and should
+     * prefer the 3-argument form `nestedRule(input, undefined, context)` so
+     * the validator wrapper doesn't extend the context a second time.
+     *
+     * @param options - Fields to override on the child context; `undefined`
+     *   values are skipped so they fall through to the parent instead of
+     *   shadowing it.
+     * @returns A new `Context` with `isRoot: false`, prototypically inheriting from this one.
+     */
     extend(options) {
         // Object.create(this) sets the prototype at creation time. Setting it
         // afterward via Object.setPrototypeOf() (the previous approach) is one

package/core/types.d.ts

@@ -1,24 +1,64 @@
 import type { Context } from './context.js';
+/**
+ * Describes a single validation failure recorded during a validator run.
+ *
+ * One `ErrorIssue` is created per failed check - a single {@link ValidationError}
+ * can carry more than one, e.g. when `isObject` validates several properties.
+ */
 export interface ErrorIssue {
+    /** The (already template-resolved) human-readable failure message. */
     message: string;
+    /** The id of the validator that reported this issue, e.g. `"isEmail"`. */
     rule: string;
+    /** The offending value that failed validation. */
     value: any;
+    /** An identifying name for the root value being validated (e.g. a schema's class name), inherited from the root {@link Context}. */
     root?: string;
+    /** A dotted/bracketed path to the failing value, e.g. `"user.email"` or `"items[0]"`. */
     location?: string;
+    /** A human-readable name for the object/schema the failing property belongs to. */
     context?: string;
+    /** The name of the failing property, when the issue originates from an object schema. */
     property?: string;
+    /** The index of the failing item, when the issue originates from an array/tuple. */
     index?: number;
+    /** A human-readable label for the failing value, used to resolve `{{label}}` in message templates. */
     label?: string;
     [key: string]: any;
 }
+/**
+ * Intercepts a validation failure before it is recorded.
+ *
+ * Return a `string` to replace the issue's message, a partial {@link ErrorIssue}
+ * to merge onto it, or a falsy value to discard the issue entirely (as if
+ * validation had passed for this particular check).
+ *
+ * @param issue - The issue that is about to be recorded.
+ * @param context - The {@link Context} the failure occurred in.
+ * @returns A replacement message, a partial issue to merge in, or a falsy value to discard the issue.
+ */
 export type OnFailFunction = (issue: ErrorIssue, context: Context) => string | Omit<ErrorIssue, 'id' | 'input'>;
+/**
+ * Options accepted by the {@link validator} factory - as opposed to per-call
+ * {@link ExecutionOptions}, these configure a rule's default behavior for
+ * every call unless overridden.
+ */
 export interface ValidationOptions {
+    /** Intercepts every failure this rule records. */
     onFail?: OnFailFunction;
+    /** Enables coercion by default, for rules that support it. */
     coerce?: boolean;
 }
+/**
+ * Options accepted on a per-call basis by every {@link Validator}, in
+ * addition to whatever rule-specific options a given validator documents.
+ */
 export interface ExecutionOptions extends ValidationOptions {
+    /** When `true`, and the rule supports it, coerces compatible input into the target type instead of rejecting it. */
     coerce?: boolean;
+    /** Stops collecting further issues (and throws immediately) once this many have been recorded. Defaults to unlimited. */
     maxErrors?: number;
+    /** A human-readable name for the value being validated, used to resolve `{{label}}` in message templates instead of the raw property name. */
     label?: string;
     [key: string]: any;
 }

package/core/utilities.d.ts

@@ -1,12 +1,52 @@
 import type { Context } from './context.js';
 import { type Validator } from './validator.js';
 /**
- * Forwards codec process to a sub codec. Useful for circular checks
+ * Defers to a validator produced lazily by `fn`, so a schema can reference
+ * itself (directly, or through a cycle of other schemas) without a
+ * "used before defined" error.
+ *
+ * @typeParam T - The output type of the resolved validator.
+ * @typeParam I - The input type of the resolved validator.
+ * @param fn - Called on every validation to resolve the actual validator to
+ *   delegate to - receives the current {@link Context} in case the
+ *   resolution needs it.
+ * @returns A validator that resolves and delegates to `fn(context)` on every call.
+ *
+ * @example
+ * ```ts
+ * import { forwardRef, vg } from 'valgen';
+ *
+ * // self-referential schema, e.g. a tree node
+ * const treeNode = vg.isObject({
+ *   value: vg.isNumber(),
+ *   children: vg.optional(vg.isArray(forwardRef(() => treeNode))),
+ * });
+ * ```
  * @validator forwardRef
  */
 export declare function forwardRef<T, I>(fn: (context: Context) => Validator<T, I>): Validator<T, I, import("./types.js").ExecutionOptions>;
 /**
- * if "check" codec passes returns "then", "else" otherwise
+ * Picks between two validators (or plain values) based on whether `check`
+ * passes against the input.
+ *
+ * @typeParam TOutput1 - The output type when `check` passes and `than_` is a validator.
+ * @typeParam TOutput2 - The output type when `check` fails and `else_` is a validator.
+ * @typeParam TDefault1 - The type of `than_` when it is a plain (non-validator) value.
+ * @typeParam TDefault2 - The type of `else_` when it is a plain (non-validator) value.
+ * @param check - Tried against the input; success (no throw) selects `than_`, failure selects `else_`.
+ * @param than_ - Used when `check` passes: a validator to run against the
+ *   input, or a constant value to return as-is (ignoring the input).
+ * @param else_ - Used when `check` fails: a validator to run against the
+ *   input, or a constant value to return as-is. Defaults to `undefined` when omitted.
+ * @returns A validator that resolves to whichever branch `check` selects.
+ *
+ * @example
+ * ```ts
+ * import { iif, isDefined, isNumber, isString } from 'valgen';
+ *
+ * // coerce differently depending on whether the value is present
+ * iif(isDefined, isString, isNumber)(1, { coerce: true }); // => '1'
+ * ```
  * @validator iif
  */
 export declare function iif<TOutput1, TOutput2, TDefault1, TDefault2>(check: Validator<any>, than_: TDefault1 | Validator<TOutput1, any>, else_?: TDefault2 | Validator<TOutput2, any>): any;

package/core/utilities.js

@@ -1,6 +1,26 @@
 import { isValidator, validator } from './validator.js';
 /**
- * Forwards codec process to a sub codec. Useful for circular checks
+ * Defers to a validator produced lazily by `fn`, so a schema can reference
+ * itself (directly, or through a cycle of other schemas) without a
+ * "used before defined" error.
+ *
+ * @typeParam T - The output type of the resolved validator.
+ * @typeParam I - The input type of the resolved validator.
+ * @param fn - Called on every validation to resolve the actual validator to
+ *   delegate to - receives the current {@link Context} in case the
+ *   resolution needs it.
+ * @returns A validator that resolves and delegates to `fn(context)` on every call.
+ *
+ * @example
+ * ```ts
+ * import { forwardRef, vg } from 'valgen';
+ *
+ * // self-referential schema, e.g. a tree node
+ * const treeNode = vg.isObject({
+ *   value: vg.isNumber(),
+ *   children: vg.optional(vg.isArray(forwardRef(() => treeNode))),
+ * });
+ * ```
  * @validator forwardRef
  */
 export function forwardRef(fn) {

package/core/validation-error.d.ts

@@ -1,5 +1,18 @@
 import { type ErrorIssue } from './types.js';
+/**
+ * Thrown by a {@link Validator} when validation fails at the root call (as
+ * opposed to `.silent()`, which returns a `{ errors }` result instead).
+ *
+ * Carries every {@link ErrorIssue} recorded during the run, not just the
+ * first one - inspect `issues` for the full list of failures, e.g. every
+ * failing property of an `isObject` schema.
+ */
 export declare class ValidationError extends Error {
+    /** Every issue recorded during this validation run, in the order they occurred. */
     issues: ErrorIssue[];
+    /**
+     * @param issues - The recorded issues. The error's own `message` (and
+     *   optional `\n  at <location>` suffix) is derived from `issues[0]`.
+     */
     constructor(issues: ErrorIssue[]);
 }

package/core/validation-error.js

@@ -1,6 +1,19 @@
 import {} from './types.js';
+/**
+ * Thrown by a {@link Validator} when validation fails at the root call (as
+ * opposed to `.silent()`, which returns a `{ errors }` result instead).
+ *
+ * Carries every {@link ErrorIssue} recorded during the run, not just the
+ * first one - inspect `issues` for the full list of failures, e.g. every
+ * failing property of an `isObject` schema.
+ */
 export class ValidationError extends Error {
+    /** Every issue recorded during this validation run, in the order they occurred. */
     issues = [];
+    /**
+     * @param issues - The recorded issues. The error's own `message` (and
+     *   optional `\n  at <location>` suffix) is derived from `issues[0]`.
+     */
     constructor(issues) {
         super(issues[0].message +
             (issues[0].location ? `\n  at ${issues[0].location}` : ''));

package/core/validator.d.ts

@@ -2,17 +2,117 @@ import type { Nullish } from 'ts-gems';
 import { kValidatorFn } from './constants.js';
 import { Context } from './context.js';
 import type { ErrorIssue, ExecutionOptions, ValidationOptions } from './types.js';
+/**
+ * The validation logic a {@link Validator} is built from - the function
+ * passed to {@link validator}.
+ *
+ * @typeParam T - The output type on success.
+ * @typeParam I - The accepted input type.
+ * @typeParam R - The `Validator` this function is built into.
+ * @param input - The value to validate.
+ * @param context - The current {@link Context}: carries execution options
+ *   (`coerce`, `label`, ...) and is used to report failures via `context.fail(...)`.
+ * @param _this - The `Validator` this function was built into - pass it to
+ *   `context.fail()` so a reported issue is attributed to the right rule.
+ * @returns The validated (and possibly coerced) value. To reject the input,
+ *   call `context.fail(_this, message, input)` instead of throwing directly.
+ */
 export type ValidateFunction<T, I = T, R extends Validator<T, I> = Validator<T, I>> = (input: I, context: Context, _this: R) => Nullish<T>;
+/**
+ * A callable validation rule, as produced by {@link validator}. Every rule in
+ * this library - and any custom rule built with `validator()` - has this shape.
+ *
+ * @typeParam T - The validated output type.
+ * @typeParam I - The accepted input type.
+ * @typeParam O - The shape of the per-call options this validator accepts.
+ *
+ * @example
+ * ```ts
+ * import { isEmail } from 'valgen';
+ *
+ * isEmail('a@b.com'); // => 'a@b.com'
+ * isEmail('invalid'); // throws ValidationError
+ * isEmail.silent('invalid'); // => { errors: [...] }
+ * ```
+ */
 export interface Validator<T = any, I = any, O extends ExecutionOptions = ExecutionOptions> {
+    /**
+     * Validates `input`, returning the (possibly coerced) value on success.
+     *
+     * @param input - The value to validate.
+     * @param options - Per-call execution options (`coerce`, `label`, ...).
+     * @param context - An existing {@link Context} to nest this call under
+     *   another validator's run. When calling a validator *from inside another
+     *   rule*, pass the shared context here (3rd argument) and `undefined` for
+     *   `options`, so the wrapper can skip an unneeded `context.extend()`.
+     * @returns The validated (and possibly coerced) value.
+     * @throws {@link ValidationError} if validation fails at the root call
+     *   (i.e. `context` was not passed in, meaning this is the outermost call).
+     */
     (input: I, options?: O, context?: Context): T;
+    /**
+     * Like calling the validator directly, but never throws.
+     *
+     * @returns `{ value }` on success, or `{ errors }` (the recorded {@link ErrorIssue}s) on failure.
+     */
     silent(input: I, options?: O, context?: Context): {
         value?: T;
         errors?: ErrorIssue[];
     };
+    /** This rule's identifier (e.g. `"isEmail"`), used to attribute reported issues to it. */
     id: string;
     args?: Record<string, any>;
     [kValidatorFn]: ValidateFunction<T, I>;
 }
+/**
+ * Builds a {@link Validator} from a validation function.
+ *
+ * This is the single factory every rule in this library - and any custom
+ * rule you write - is built with. See {@link ValidateFunction} for the shape
+ * expected of `fn`.
+ *
+ * @param fn - The validation logic: receives `(input, context, self)` and
+ *   should return the validated value, or call `context.fail(self, message, input)`
+ *   to record a failure. The rule's id defaults to `fn.name`.
+ * @param validatorOptions - Default options for this rule (e.g. `coerce`,
+ *   `onFail`), applied to every call unless overridden per-call.
+ * @returns A callable {@link Validator}.
+ *
+ * @example
+ * ```ts
+ * import { validator, type Context, type Nullish, type ValidationOptions } from 'valgen';
+ *
+ * function isEven(options?: isEven.Options) {
+ *   return validator<number, unknown>(
+ *     isEven.name,
+ *     (input, context, self): Nullish<number> => {
+ *       const n = Number(input);
+ *       if (Number.isInteger(n) && n % 2 === 0) return n;
+ *       context.fail(self, 'Value must be an even number', input);
+ *     },
+ *     options,
+ *   );
+ * }
+ * namespace isEven {
+ *   export interface Options extends ValidationOptions {}
+ * }
+ * ```
+ */
 export declare function validator<T, I = T, O extends ExecutionOptions = ExecutionOptions>(fn: ValidateFunction<T, I>, validatorOptions?: ValidationOptions): Validator<T, I, O>;
+/**
+ * Builds a {@link Validator} from a validation function, with an explicit id.
+ *
+ * @param id - The rule's identifier, used for `Validator.id` and (unless `fn`
+ *   is itself named) as the built function's name.
+ * @param fn - The validation logic - see the other overload for details.
+ * @param validatorOptions - Default options for this rule.
+ * @returns A callable {@link Validator}.
+ */
 export declare function validator<T, I = T, O extends ExecutionOptions = ExecutionOptions>(id: string, fn: ValidateFunction<T, I>, validatorOptions?: ValidationOptions): Validator<T, I, O>;
+/**
+ * Checks whether `x` is a {@link Validator} built with {@link validator}.
+ *
+ * @param x - The value to check.
+ * @returns `true` if `x` is a validator, narrowing its type accordingly.
+ */
 export declare function isValidator(x: any): x is Validator;

package/core/validator.js

@@ -62,6 +62,12 @@ export function validator(arg0, arg1, arg2) {
     };
     return _rule;
 }
+/**
+ * Checks whether `x` is a {@link Validator} built with {@link validator}.
+ *
+ * @param x - The value to check.
+ * @returns `true` if `x` is a validator, narrowing its type accordingly.
+ */
 export function isValidator(x) {
     return !!(typeof x === 'function' && x.id && x[kValidatorFn]);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "valgen",
   "description": "Fast runtime type validator, converter and io (encoding/decoding) library",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/rules/format-rules/is-alpha.d.ts

@@ -1,7 +1,16 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Check if the string contains only letters (a-zA-Z).
+ * Validates that a string contains only letters (`a-zA-Z`). Delegates to
+ * `validatorJS.isAlpha`.
  * @validator isAlpha
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a string of letters only: `Value must be an alpha string`
+ * @example
+ * ```ts
+ * isAlpha('abcDEF'); // => 'abcDEF'
+ * isAlpha('abc123'); // throws ValidationError: "Value must be an alpha string"
+ * ```
  */
 export declare function isAlpha(options?: isAlpha.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isAlpha {

package/rules/format-rules/is-alpha.js

@@ -1,8 +1,17 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Check if the string contains only letters (a-zA-Z).
+ * Validates that a string contains only letters (`a-zA-Z`). Delegates to
+ * `validatorJS.isAlpha`.
  * @validator isAlpha
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a string of letters only: `Value must be an alpha string`
+ * @example
+ * ```ts
+ * isAlpha('abcDEF'); // => 'abcDEF'
+ * isAlpha('abc123'); // throws ValidationError: "Value must be an alpha string"
+ * ```
  */
 export function isAlpha(options) {
     return validator(isAlpha.name, (input, context, _this) => {

package/rules/format-rules/is-alphanumeric.d.ts

@@ -1,7 +1,16 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Check if the string contains only letters and numbers.
+ * Validates that a string contains only letters and numbers. Delegates to
+ * `validatorJS.isAlphanumeric`.
  * @validator isAlphanumeric
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a string of letters/numbers only: `Value must be an alphanumeric string`
+ * @example
+ * ```ts
+ * isAlphanumeric('abc123'); // => 'abc123'
+ * isAlphanumeric('abc-123'); // throws ValidationError: "Value must be an alphanumeric string"
+ * ```
  */
 export declare function isAlphanumeric(options?: isAlphanumeric.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isAlphanumeric {

package/rules/format-rules/is-alphanumeric.js

@@ -1,8 +1,17 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Check if the string contains only letters and numbers.
+ * Validates that a string contains only letters and numbers. Delegates to
+ * `validatorJS.isAlphanumeric`.
  * @validator isAlphanumeric
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a string of letters/numbers only: `Value must be an alphanumeric string`
+ * @example
+ * ```ts
+ * isAlphanumeric('abc123'); // => 'abc123'
+ * isAlphanumeric('abc-123'); // throws ValidationError: "Value must be an alphanumeric string"
+ * ```
  */
 export function isAlphanumeric(options) {
     return validator(isAlphanumeric.name, (input, context, _this) => {

package/rules/format-rules/is-ascii.d.ts

@@ -1,7 +1,16 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Check if the string contains ASCII chars only.
+ * Validates that a string contains only ASCII characters. Delegates to
+ * `validatorJS.isAscii`.
  * @validator isAscii
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` contains non-ASCII characters: `Value must be an ascii string`
+ * @example
+ * ```ts
+ * isAscii('abc123!@#'); // => 'abc123!@#'
+ * isAscii('şiir'); // throws ValidationError: "Value must be an ascii string"
+ * ```
  */
 export declare function isAscii(options?: isAscii.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isAscii {

package/rules/format-rules/is-ascii.js

@@ -1,8 +1,17 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Check if the string contains ASCII chars only.
+ * Validates that a string contains only ASCII characters. Delegates to
+ * `validatorJS.isAscii`.
  * @validator isAscii
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` contains non-ASCII characters: `Value must be an ascii string`
+ * @example
+ * ```ts
+ * isAscii('abc123!@#'); // => 'abc123!@#'
+ * isAscii('şiir'); // throws ValidationError: "Value must be an ascii string"
+ * ```
  */
 export function isAscii(options) {
     return validator(isAscii.name, (input, context, _this) => {