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.