validators library

Top‑level built‑in validators and combinators.

Overview:

• Stateless type validators: isString(), isInt(), isMap(), etc. Each has a cached $ alias ($isString, $isInt) for zero‑arg reuse.
• Logical/comparison: isGt, isGte, isLt, isLte, isEq, isDeepEq.
• Collection / structure helpers: contains, containsKey, listEach, eskema, eskemaList.
• String/length: stringIsOfLength, stringContains, stringMatchesPattern.
• Numeric/string parsing predicates: isIntString, isDoubleString, isNumString.
• Date/time: isDate (parsable ISO 8601 string), isDateTime (actual DateTime type).
• Combinators:
  • all([...]) AND composition (short‑circuits on first failure)
  • any([...]) OR composition (returns first success, else aggregates failures)
  • none([...]) succeeds only if every validator fails
  • not(v) logical negation
• Null / presence semantics:
  • nullable(v) (or v.nullable()) => key must exist; value may be null
  • optional(v) (or v.optional()) => key may be missing; if present must pass v
• Schema helpers:
  • eskema({...}) for Map field validation (propagates nested error paths)
  • eskemaList([...]) positional list schema
  • listEach(v) uniform element validation
• Utility wrappers:
  • withError(child, message) replace expectation message

Value flow:

• Basic validators are pure predicates that attach Expectations.
• Combinators compose results; all stops early, any returns on first pass.
• Transformers (defined separately) can precede these validators; all will forward transformed values to subsequent validators.

Conventions:

• Prefer $isType constants for zero‑arg validators in hot paths.
• For collection equality use isDeepEq instead of isEq on lists/maps/sets.

See README for detailed examples and nullable vs optional explanation.

This library is intentionally minimal: advanced behaviors (async validators, transformers, refiners) live in their own files to keep this surface stable.

Properties

$isBool → IValidator

Cached instance of isBool. Validates that the value is a bool.

final

$isBoolString → IValidator

Cached instance of isBoolString. Validates that the string can be parsed as a boolean.

final

$isDate → IValidator

Cached instance of isDate. Validates that the string is a valid DateTime format.

final

$isDateTime → IValidator

Cached instance of isDateTime. Validates that the value is a DateTime.

final

$isDouble → IValidator

Cached instance of isDouble. Validates that the value is a double.

final

$isDoubleString → IValidator

Cached instance of isDoubleString. Validates that the string can be parsed as a double.

final

$isEmail → IValidator

Cached instance of isEmail. Validates that the string is a valid email address.

final

$isEnum → IValidator

Cached instance of isEnum. Validates that the value is an enum value.

final

$isFunction → IValidator

Cached instance of isFunction. Validates that the value is a Function.

final

$isFuture → IValidator

Cached instance of isFuture. Validates that the value is a Future.

final

$isInt → IValidator

Cached instance of isInt. Validates that the value is an int.

final

$isIntString → IValidator

Cached instance of isIntString. Validates that the string can be parsed as an integer.

final

$isIterable → IValidator

Cached instance of isIterable. Validates that the value is an Iterable.

final

$isList → IValidator

Cached instance of isList. Validates that the value is a List.

final

$isLowerCase → IValidator

Cached instance of isLowerCase. Validates that the string contains only lowercase characters.

final

$isMap → IValidator

Cached instance of isMap. Validates that the value is a Map.

final

$isNonEmptyList → IValidator

Cached instance for a present (non-null AND non-empty) list. Equivalent to: all([$isList, $listNotEmpty]).

final

$isNonEmptyString → IValidator

Cached instance representing a non-empty String. Equivalent to: all([$isString, not($isStringEmpty)]). Valid when the value is a String and not empty.

final

$isNotNull → IValidator

Cached instance representing NOT null (i.e. value must be non-null). Equivalent to: not($isNull).

final

$isNull → IValidator

Cached instance of isNull. Validates that the value is null.

final

$isNumber → IValidator

Cached instance of isNumber. Validates that the value is a num (int or double).

final

$isNumString → IValidator

Cached instance of isNumString. Validates that the string can be parsed as a number.

final

$isRecord → IValidator

Cached instance of isRecord. Validates that the value is a Record.

final

$isSet → IValidator

Cached instance of isSet. Validates that the value is a Set.

final

$isStrictUrl → IValidator

Cached instance of isStrictUrl. Validates that the string is a valid URL with strict requirements.

final

$isString → IValidator

Cached instance of isString. Validates that the value is a String.

final

$isStringEmpty → IValidator

Cached instance of isStringEmpty. Validates that the value is empty (string, list, map, etc.).

final

$isSymbol → IValidator

Cached instance of isSymbol. Validates that the value is a Symbol.

final

$isUpperCase → IValidator

Cached instance of isUpperCase. Validates that the string contains only uppercase characters.

final

$isUrl → IValidator

Cached instance of isUrl. Validates that the string is a valid URL.

final

$isUuidV4 → IValidator

Cached instance of isUuidV4. Validates that the string is a valid UUID v4.

final

$listEmpty → IValidator

Cached instance of listEmpty. Validates that the list is empty.

final

$listNotEmpty → IValidator

Cached instance of not applied to $listEmpty. Validates that the list is not empty.

final

$optionalNonEmptyList → IValidator

Cached instance for a nullable non-empty list (null passes, empty list fails).

final

$optionalNonEmptyString → IValidator

Cached instance for optional (nullable) non-empty string: accepts null OR a non-empty string. Usage: $optionalNonEmptyString.validate(null) -> valid; .validate('') -> invalid.

final

emailRegex → RegExp

final

uuidRegex → RegExp

final

Functions

all(List<IValidator> validators, {String? message, bool collecting = false}) → AllValidator

Passes the test if all of the Validators are valid, and fails if any of them are invalid

any(List<IValidator> validators, {String? message}) → IValidator

Passes the test if any of the Validators are valid, and fails if any are invalid

contains<T>(T item, {String? message}) → IValidator

Checks whether the given value contains the item value of type T

containsKey(String key, {String? message}) → IValidator

Validator that checks if a map contains a specific key.

containsKeys(Iterable<String> keys, {String? message}) → IValidator

Validator that checks if a map contains a specific set of keys.

containsValues(Iterable values, {String? message}) → IValidator

Validator that checks if a map contains a specific set of values.

eskema(Map<String, IValidator> mapEskema, {String? message}) → IValidator

Returns a Validator that checks a value against a Map eskema that declares a validator for each key.

eskemaList<T>(List<IValidator> eskema) → IValidator

Returns a Validator that checks a value against the eskema provided, the eskema defines a validator for each item in the list

eskemaStrict(Map<String, IValidator> schema, {String? message}) → IValidator

Returns a Validator that checks a value against a Map eskema and fails if any keys exist in the map that are not defined in the schema.

isBool({String? message}) → IValidator

Returns a IValidator that checks if the given value is a bool For better performance and readability, use the $isBool variable directly.

isBoolString({String? message}) → IValidator

Validates that the String can be parsed as a bool ('true' or 'false', case insensitive)

isDate({String? message}) → IValidator

Checks whether the given value is a valid DateTime formatted String

isDateAfter(DateTime dt, {bool inclusive = false, String? message}) → IValidator

DateTime must be after (or equal if inclusive) given bound.

isDateBefore(DateTime dt, {bool inclusive = false, String? message}) → IValidator

DateTime must be before (or equal if inclusive) given bound.

isDateBetween(DateTime start, DateTime end, {bool inclusiveStart = true, bool inclusiveEnd = true, String? message}) → IValidator

DateTime must fall within the interval.

isDateInFuture({bool allowNow = true, String? message}) → IValidator

DateTime must be in the future.

isDateInPast({bool allowNow = true, String? message}) → IValidator

DateTime must be in the past.

isDateSameDay(DateTime dt, {String? message}) → IValidator

DateTime must be same calendar day.

isDateTime({String? message}) → IValidator

Returns a IValidator that checks if the given value is a DateTime For better performance and readability, use the $isDateTime variable directly.

isDeepEq<T>(T otherValue, {String? message}) → IValidator

Checks whether the given value is equal to the otherValue value of type T

isDouble({String? message}) → IValidator

Returns a IValidator that checks if the given value is a double For better performance and readability, use the $isDouble variable directly.

isDoubleString({String? message}) → IValidator

Validates that the String can be parsed as a double (e.g. '123.45', '-1e3')

isEmail({String? message}) → IValidator

Validates that the String is a valid email address.

isEnum({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Enum For better performance and readability, use the $isEnum variable directly.

isEq<T>(T otherValue, {String? message}) → IValidator

Checks whether the given value is equal to the otherValue value of type T

isFunction({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Function For better performance and readability, use the $isFunction variable directly.

isFuture<T>({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Future For better performance and readability, use the $isFuture variable directly.

isGt<T extends num>(T min, {String? message}) → IValidator

Checks whether the given value is greater than min

isGte<T extends num>(T min, {String? message}) → IValidator

Checks whether the given value is greater or equal to min

isInRange<T extends num>(T min, T max, {String? message}) → IValidator

Checks whether the given numeric value is within the range min, max (inclusive).

isInt({String? message}) → IValidator

Returns a IValidator that checks if the given value is a int For better performance and readability, use the $isInt variable directly.

isIntString({String? message}) → IValidator

Validates that the String can be parsed as an int (e.g. '123', '-42')

isIterable<T>({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Iterable For better performance and readability, use the $isIterable variable directly.

isList<T>({String? message}) → IValidator

Returns a IValidator that checks if the given value is a List For better performance and readability, use the $isList variable directly.

isLowerCase({String? message}) → IValidator

Validates that it's a String and it's lowecase

isLt<T extends num>(T max, {String? message}) → IValidator

Checks whether the given value is less than max

isLte<T extends num>(T max, {String? message}) → IValidator

Checks whether the given value is less than or equal max

isMap<K, V>({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Map For better performance and readability, use the $isMap variable directly.

isNull({String? message}) → IValidator

Returns a IValidator that checks if the given value is null For better performance and readability, use the $isNull variable directly.

isNumber({String? message}) → IValidator

Returns a IValidator that checks if the given value is a num For better performance and readability, use the $isNumber variable directly.

isNumString({String? message}) → IValidator

Validates that the String can be parsed as a num (int or double)

isOneOf<T>(Iterable<T> options, {String? message}) → IValidator

Checks whether the given value is one of the options values of type T

isRecord({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Record

isSet<T>({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Set For better performance and readability, use the $isSet variable directly.

isStrictUrl({String? message}) → IValidator

isString({String? message}) → IValidator

Returns a IValidator that checks if the given value is a String For better performance and readability, use the $isString variable directly.

isStringEmpty({String? message}) → IValidator

Checks whether the given string is empty

isSymbol({String? message}) → IValidator

Returns a IValidator that checks if the given value is a Symbol For better performance and readability, use the $isSymbol variable directly.

isType<T>({String? message}) → IValidator

Returns a Validator that checks if the given value is the correct type

isTypeOrNull<T>({String? message}) → IValidator

Returns a Validator that checks if the given value is the correct type

isUpperCase({String? message}) → IValidator

Validates that it's a String and it's uppercase

isUrl({bool strict = false, String? message}) → IValidator

Validates that the String is a valid URL. By it uses non-strict validation (like "example.com").

isUuidV4({String? message}) → IValidator

Validates that the String is a valid UUID (v4).

length(List<IValidator> validators, {String? message}) → IValidator

Checks whether the given value has a length property and the length matches the validators

listContains<T>(dynamic item, {String? message}) → IValidator

Validates that the List contains item

listEach(IValidator itemValidator, {String? message}) → IValidator

Returns a Validator that runs itemValidator for each item in the list

listEmpty<T>({String? message}) → IValidator

Validate that the list is empty

listIsOfLength(int size, {String? message}) → IValidator

Validates that it's a list of size length

listLength<T>(List<IValidator> validators, {String? message}) → IValidator

Validates that it's a List and the length matches the validators

none(List<IValidator> validators, {String? message}) → IValidator

Passes the test if none of the validators pass

not(IValidator child, {String? message}) → IValidator

Passes the test if the child validator is not valid

nullable(IValidator validator) → IValidator

If the field is not present (null) it will be considered valid If you want to allow empty strings as valid, use optional instead

optional(IValidator validator) → IValidator

If the field is not present, it will be considered valid, if present, it executes the validator. It's different from nullable in that it also checks for empty strings

stringContains(String str, {String? message}) → IValidator

Validates that the String contains str

stringIsOfLength(int size, {String? message}) → IValidator

Validates that the String's length is the same as the provided size

stringLength(List<IValidator> validators, {String? message}) → IValidator

Validates that the String's length matches the validators

stringMatchesPattern(Pattern pattern, {String? message}) → IValidator

Validates that the String matches the provided pattern

throwInstead(IValidator validator) → IValidator

Returns a Validator that throws a ValidatorFailedException instead of returning a result

validator(bool comparisonFn(dynamic value), Expectation errorFn(dynamic value)) → Validator<Result>

when(IValidator condition, {required IValidator then, required IValidator otherwise, String? message}) → IValidator

Creates a conditional validator. It's conditional based on some other field in the eskema.

withExpectation(IValidator child, Expectation error, {String? message}) → IValidator

Returns a IValidator that wraps the given child validator and adds the provided error message to the result if the validation fails. Preserves the underlying child's code and data (if the child failed). See docs/expectation_codes.md.