shelving/util/validate.d.ts

Toolkit for using data in JavaScript.

import type { BaseError, BaseErrorOptions } from "../error/BaseError.js";
import type { ImmutableArray, PossibleArray } from "./array.js";
import type { Constructor } from "./class.js";
import type { Data } from "./data.js";
import type { ImmutableDictionary } from "./dictionary.js";
import type { AnyCaller } from "./function.js";
import type { DeepPartial } from "./object.js";
/** Object that can validate an unknown value with its `validate()` method. */
export interface Validator<T> {
    /**
     * `validate()` method accepts an unsafe value and returns a valid value.
     *
     * @param unsafeValue A potentially invalid value.
     *
     * @return Valid value.
     *
     * @throws `Error` If the value is invalid and cannot be fixed.
     * @throws `Feedback` If the value is invalid and cannot be fixed and we want to explain why to an end user.
     */
    validate(unsafeValue: unknown): T;
}
/** Extract the type from a validator. */
export type ValidatorType<X> = X extends Validator<infer Y> ? Y : never;
/** A set of named validators in `{ name: Validator }` format. */
export type Validators<T extends Data = Data> = {
    readonly [K in keyof T]: Validator<T[K]>;
};
/** Extract the type from a set of validators. */
export type ValidatorsType<T> = {
    readonly [K in keyof T]: ValidatorType<T[K]>;
};
/** Get value that validates against a given `Validator`, or throw `ValueError` */
export declare function getValid<T>(value: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>, caller?: AnyCaller): T;
/**
 * Validate an iterable set of items with a validator.
 *
 * @yield Valid items.
 * @throw Feedback if one or more items did not validate.
 * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
 */
export declare function validateItems<T>(unsafeItems: PossibleArray<unknown>, validator: Validator<T>): Iterable<T>;
/**
 * Validate an array of items.
 *
 * @return Array with valid items.
 * @throw Feedback if one or more entry values did not validate.
 * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
 */
export declare function validateArray<T>(unsafeArray: PossibleArray<unknown>, validator: Validator<T>): ImmutableArray<T>;
/**
 * Validate the values of the entries in a dictionary object.
 *
 * @throw Feedback if one or more entry values did not validate.
 * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
 */
export declare function validateDictionary<T>(unsafeDictionary: ImmutableDictionary<unknown>, validator: Validator<T>): ImmutableDictionary<T>;
/**
 * Validate a data object with a set of validators.
 * - Defined props in the object will be validated against the corresponding validator.
 * - `undefined` props in the object will be set to the default value of that prop.
 *
 * @param partial Whether we're validating a partial match, or not.
 * @return Valid object.
 * @throw Feedback if one or more props did not validate.
 * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
 */
export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>, partial: true): DeepPartial<T>;
export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>, partial?: false): T;
export declare const UNDEFINED: Validator<undefined>;
export declare const NULL: Validator<null>;
export declare const UNKNOWN: Validator<unknown>;