transformers library

Transformers

Value–coercion helpers that run BEFORE the provided child validator. They:

  • Accept a broader set of input types (e.g. int / num / String for toInt)
  • Produce a (possibly) transformed value
  • Pass that value to the child validator

Failure model:

  • The “pre‑check” part (e.g. $isInt | $isNumber | $isIntString) ensures only plausible values reach the mapper. If that OR validator fails, the chain stops there (no transform executed).
  • The transform(...) function itself NEVER throws; it may return null. If it returns null, the child validator receives null (and will typically fail unless it is nullable()).

Composition patterns:

  • Coerce then constrain: final age = toInt(isGte(0) & isLte(130));
  • Add null support after coercion: final maybeDate = toDateTime(isType<DateTime>()).nullable();
  • Field extraction + transform: final userAge = getField('age', toInt(isGte(18)));

Expectations:

  • If you supply a message parameter to a transformer factory, an overriding expectation is attached. Omitting message preserves the underlying validators' original expectations (backward compatible behavior).

NOTE: These are “inline transformers” — they do not mutate external data, only the value flowing through the validator pipeline.

Functions

collapseWhitespace(IValidator child, {String? message}) → IValidator
Collapse internal whitespace runs to a single space and trim ends.
defaultTo(dynamic defaultValue, IValidator child, {String? message}) → IValidator
Provides a default value if the input is null.
expectPreserveValue(IValidator validator, Expectation expectation) → IValidator
Adds an expectation message while preserving the child's resulting value (useful for coercions where later constraints rely on the coerced type even on failure).
flattenMapKeys(String delimiter, IValidator child, {String? message}) → IValidator
Flattens a nested Map structure into a single-level Map using the provided delimiter. Only flattens nested Maps (non-Map values become leaves). Arrays/lists are left as-is.
getField(String key, IValidator inner) → IValidator
Extracts and validates a field from a map.
handleReturnPreserveValue(IValidator validator, String? message) → IValidator
pickKeys(Iterable<String> keys, IValidator child, {String? message}) → IValidator
Picks a subset of keys from a Map, producing a new Map with only those keys present (if they existed). Fails if input is not a Map.
pivotValue(dynamic transformFn(dynamic value), {required IValidator child, required String errorMessage}) → IValidator
Unified helper for value pivoting operations.
pluckKey(String key, IValidator child, {String? message}) → IValidator
Plucks a single key's value from a Map (similar to getField but transform style).
split(String separator, IValidator child, {String? message}) → IValidator
Splits a string into a list of substrings.
toBigInt(IValidator child, {String? message}) → IValidator
Coerces value to a BigInt.
toBool(IValidator child, {String? message}) → IValidator
Coerces a value to a boolean (standard mode).
toBoolLenient(IValidator child, {String? message}) → IValidator
Lenient / permissive bool coercion.
toBoolStrict(IValidator child, {String? message}) → IValidator
Strict bool coercion.
toDateTime(IValidator child, {String? message}) → IValidator
Coerces a value to a DateTime.
toDouble(IValidator child, {String? message}) → IValidator
Coerces a value to a double.
toInt(IValidator child, {String? message}) → IValidator
Coerces a value to an integer.
toIntSafe(IValidator child, {String? message}) → IValidator
Safe integer coercion (strict + 53-bit range guard).
toIntStrict(IValidator child, {String? message}) → IValidator
Strict integer coercion.
toJsonDecoded(IValidator child, {String? message}) → IValidator
Coerces a JSON string into its decoded form (Map/List). Leaves existing Map/List untouched.
toLowerCase(IValidator child, {String? message}) → IValidator
Transforms a string to lowercase.
toLowerCaseString(IValidator child, {String? message}) → IValidator
Lowercase string (ASCII-focused; leaves non-letters unchanged).
toNum(IValidator child, {String? message}) → IValidator
Coerces a value to a number (num).
toString(IValidator child, {String? message}) → IValidator
Coerces a value to a String.
toUpperCase(IValidator child, {String? message}) → IValidator
Transforms a string to uppercase.
toUpperCaseString(IValidator child, {String? message}) → IValidator
Uppercase string.
transform<T>(T fn(dynamic), IValidator child) → IValidator
Transforms a value using a provided function.
trim(IValidator child, {String? message}) → IValidator
Trims leading and trailing whitespace from a string.
trimString(IValidator child, {String? message}) → IValidator
String normalizer (no type pivot): trim leading/trailing whitespace.