convert library
π Jetleaf Type Conversion Subsystem
This library provides the core type conversion infrastructure for Jetleaf applications, enabling safe, bi-directional transformation between disparate Dart types.
It supports:
- Core conversion services and registries.
- Built-in converters for Dart primitives, dates, durations, and enums.
- Collection and map transformations (
List<S>->List<T>,Set<S>->Set<T>). - Custom converter registration via Converter<S, T>.
- Paired type-safe lookup with generic preservation.
π Conversion Resolution Matrix
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Conversion Request β
β convert(source, Class<Target>()) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Exact Match [ConvertiblePair(Source, Target)] β
β β β
β 2. Collection Element List<S> -> List<T> via Converter<S,T>β
β β β
β 3. Enum Mapping String / Int <-> Enum constant β
β β β
β 4. Fallback String parsing / Object stringify β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π¦ Exports Categorization
βοΈ Core Conversion Engine
- ConversionService β the primary service interface for executing type conversions.
- ConverterRegistry β registry interface for adding and managing converters.
- DefaultConversionService β standard, pre-populated production conversion engine.
- SimpleConversionService β lightweight base conversion service.
- Converter β fundamental single-method contract (
T convert(S source)). - ConvertiblePair β immutable tuple identifying source and target types.
π¦ Built-In Converters
- Time Converters: StringToDurationConverter, DurationToStringConverter, StringToDateTimeConverter.
- Primitive Converters:
StringToIntConverter,StringToDoubleConverter,StringToBoolConverter. - Collection Converters: List, Set, and Map structural adapters.
π― Usage Example: Custom Converter Registration & Invocation
import 'package:jetleaf_core/convert.dart';
import 'package:jetleaf_core/lang.dart';
class Color {
final int hex;
const Color(this.hex);
@override
String toString() => '#${hex.toRadixString(16).padLeft(6, '0')}';
}
class HexToColorConverter implements Converter<String, Color> {
@override
String getPackageName() => 'my_app';
@override
Color convert(String source) {
final clean = source.replaceAll('#', '');
return Color(int.parse(clean, radix: 16));
}
}
void main() {
final service = DefaultConversionService();
// Register custom converter
service.addConverter(
HexToColorConverter(),
sourceType: Class<String>(),
targetType: Class<Color>(),
);
// Execute type-safe conversion
final color = service.convert('#FF5733', Class<Color>());
print('Converted color: $color (Hex value: ${color?.hex})');
}
Classes
- ArrayListToCollectionGenericConverter
- A converter that transforms an ArrayList to a specific collection subtype.
- BigDecimalGenericConverter
- A converter that transforms a BigDecimal to a specific numeric subtype.
- BigIntegerGenericConverter
- A converter that transforms a BigInteger to a specific numeric subtype.
- BigIntGenericConverter
- A converter that transforms a BigInt to a specific numeric subtype.
- BooleanGenericConverter
- A converter that transforms a Boolean to a specific numeric subtype.
- BoolGenericConverter
- A converter that transforms a bool to a specific numeric subtype.
- ByteMultiConverter
- A Converter that converts between Byte, String, List, and Uint8List.
- CharacterGenericConverter
- A converter that transforms a Character to a specific numeric subtype.
- CollectionToCollectionConverter
- An abstract base class for converting between different types of Dart collections, with optional element type conversion.
- ConditionalConverter
- A contract for a converter that only matches under certain conditions.
- ConfigurableConversionService
- A configurable conversion service that allows dynamic registration of converters.
- ConversionAdapterUtils
- Utility class for converting generic or adaptable collections into strongly typed collections based on Jetleaf Class metadata.
- ConversionService
- A strategy interface for type conversion.
-
ConversionServiceConverter<
S, T> - A Converter that delegates to a ConversionService for converting values.
- ConversionServiceFactory
- Utility class for registering a set of converters with a ConverterRegistry.
- ConversionUtils
- Utility class containing common operations used by conversion infrastructure.
-
Converter<
S, T> -
A generic interface for converting an input of type
Sinto an output of typeT. -
ConverterFactory<
S, R> -
A factory for creating Converter instances that convert from a source type
Sto a target typeT, whereTis a subtype ofR. - ConverterRegistry
- A registry of converters and converter factories used to perform type conversions at runtime.
- ConvertiblePair
- Represents a pair of source and target types for type conversion.
-
ConvertingComparator<
S, T> -
A comparator that compares source values of type
Sby first converting them to another typeTusing a Converter, then applying a Comparator onT. - CurrencyToStringConverter
- A Converter that converts a Currency to a String.
- DateTimeToIntConverter
- Converts DateTime to int (epoch milliseconds)
- DateTimeToLocalDateConverter
- Converts DateTime to LocalDate
- DateTimeToLocalDateTimeConverter
- Converts DateTime to LocalDateTime
- DateTimeToLocalTimeConverter
- Converts DateTime to LocalTime
- DateTimeToStringConverter
- Converts DateTime to String using ISO 8601 format
- DateTimeToZonedDateTimeConverter
- Converts DateTime to ZonedDateTime with specified zone
- DefaultConversionService
- A fully configured, ready-to-use conversion service suitable for most Jetleaf environments.
- DoubledGenericConverter
- A converter that transforms a Double to a specific numeric subtype.
- DoubleGenericConverter
- A converter that transforms a double to a specific numeric subtype.
- DurationToIntConverter
- Converts Duration to int (milliseconds)
- DurationToStringConverter
- Converts Duration to String in readable format
- EnumToIntConverter
- A Converter that converts an Enum to an int.
- EnumToStringConverter
- A Converter that converts an Enum to a String.
- FallbackObjectToStringConverter
- A Converter that converts any object to string using toString().
- FloatGenericConverter
- A converter that transforms a Float to a specific numeric subtype.
- GenericNullConverter
- A contract for a converter that only matches under certain conditions.
- HashSetToCollectionGenericConverter
- A converter that transforms a HashSet to a specific collection subtype.
- IntegerGenericConverter
- A converter that transforms a Integer to a specific numeric subtype.
- IntGenericConverter
- A converter that transforms an int to a specific numeric subtype.
- IntToDateTimeConverter
- Converts int (epoch milliseconds) to DateTime
- IntToDurationConverter
- Converts int (milliseconds) to Duration
- IntToEnumConverterFactory
- A ConverterFactory that provides converters to convert integers to enums.
- IntToZonedDateTimeConverter
- Converts int (epoch milliseconds) to ZonedDateTime
- IterableIntToStringConverter
- Workaround converter for Iterable<int> to String.
- IterableToCollectionGenericConverter
- A converter that transforms an Iterable to a specific collection subtype.
- LinkedHashSetToCollectionGenericConverter
- A converter that transforms a col.LinkedHashSet to a specific collection subtype.
- LinkedListToCollectionGenericConverter
- A converter that transforms a LinkedList to a specific collection subtype.
- LinkedQueueToCollectionGenericConverter
- A converter that transforms a LinkedQueue to a specific collection subtype.
- LinkedStackToCollectionGenericConverter
- A converter that transforms a LinkedStack to a specific collection subtype.
- ListableConverterRegistry
- A ConverterRegistry that also provides access to registered UriValidator instances.
- ListBaseToCollectionConverter
- A converter that transforms a col.ListBase to a specific collection subtype.
- ListToCollectionConverter
- A converter that transforms a List to a specific collection subtype.
- ListToObjectConverter
- A Converter that converts a List to an Object (extracts single element).
- LocalDateAndLocalTimeToLocalDateTimeConverter
- Converts LocalDate and LocalTime to LocalDateTime
- LocalDateTimeToDateTimeConverter
- Converts LocalDateTime to DateTime (assumes UTC)
- LocalDateTimeToLocalDateConverter
- Converts LocalDateTime to LocalDate
- LocalDateTimeToLocalTimeConverter
- Converts LocalDateTime to LocalTime
- LocalDateTimeToStringConverter
- Converts LocalDateTime to String using ISO 8601 format
- LocalDateTimeToZonedDateTimeConverter
- Converts LocalDateTime to ZonedDateTime with specified zone
- LocalDateToDateTimeConverter
- Converts LocalDate to DateTime (at midnight UTC)
- LocalDateToStringConverter
- Converts LocalDate to String using ISO 8601 format
- LocaleToStringConverter
- LocalTimeToStringConverter
-
Converts LocalTime to String using HH:mm:ss
.SSSformat - LongGenericConverter
- A converter that transforms a Long to a specific numeric subtype.
- MapToMapGenericConverter
- A converter that transforms a Map (or any map-like type) into another Map type, optionally converting keys and values.
- MapToStringGenericConverter
- A converter that transforms different types of Map into a String.
- NumberGenericConverter
- A converter that transforms a num to a specific numeric subtype.
- ObjectToListConverter
- A Converter that converts an Object to a List.
- ObjectToObjectConverter
- A Converter that converts an Object to another Object using reflection.
- ObjectToSetConverter
- A Converter that converts an Object to a Set.
- PairedConditionalConverter
- A bridge interface combining PairedConverter and ConditionalConverter.
- PairedConverter
- A general-purpose converter that can convert between multiple sourceβtarget type pairs.
- PatternToStringConverter
- A Converter that converts a Pattern to a String.
- QueueToCollectionGenericConverter
- A converter that transforms a Queue to a specific collection subtype.
- RegExpToStringConverter
- A Converter that converts a RegExp to a String.
- RunesToStringConverter
- A Converter that converts a Runes to a String.
- SetBaseToCollectionGenericConverter
- A converter that transforms a col.SetBase to a specific collection subtype.
- SetToCollectionGenericConverter
- A converter that transforms a Set to a specific collection subtype.
- SetToObjectConverter
- A Converter that converts a Set to an Object (extracts single element).
- ShortGenericConverter
- A converter that transforms a Short to a specific numeric subtype.
- SimpleConversionService
- A configurable and extensible conversion service that provides a central mechanism for converting between types in Jetleaf applications.
- StackToCollectionGenericConverter
- A converter that transforms a Stack to a specific collection subtype.
- StringGenericConverter
- A converter that transforms a String to a specific numeric subtype.
- StringToCurrencyConverter
- A Converter that converts a String to a Currency.
- StringToDateTimeConverter
- Comprehensive collection of converters for time-related objects.
- StringToDurationConverter
- Converts String to Duration using Duration parsing
- StringToEnumConverterFactory
- A ConverterFactory that provides converters to convert strings to enums.
- StringToLocalDateConverter
- Converts String to LocalDate using LocalDate.parse()
- StringToLocalDateTimeConverter
- Converts String to LocalDateTime using LocalDateTime.parse()
- StringToLocaleConverter
- A Converter that converts a String to a Locale.
- StringToLocalTimeConverter
- Converts String to LocalTime using LocalTime.parse()
- StringToMapGenericConverter
- A converter that transforms a String into different types of Map implementations.
- StringToPatternConverter
- A Converter that converts a String to a Pattern.
- StringToRegExpConverter
- A Converter that converts a String to a RegExp.
- StringToRunesConverter
- A Converter that converts a String to a Runes.
- StringToSymbolConverter
- A Converter that converts a String to a Symbol.
- StringToUriConverter
- A Converter that converts a String to a Uri.
- StringToUuidConverter
- A Converter that converts a String to a Uuid.
- StringToZonedDateTimeConverter
- Converts String to ZonedDateTime using ZonedDateTime.parse()
- StringToZoneIdConverter
- Converts String to ZoneId using ZoneId()
- SymbolToStringConverter
- A Converter that converts a Symbol to a String.
- UriToStringConverter
- A Converter that converts a Uri to a String.
- UuidToStringConverter
- A Converter that converts a Uuid to a String.
- ZonedDateTimeToDateTimeConverter
- Converts ZonedDateTime to DateTime
- ZonedDateTimeToIntConverter
- Converts ZonedDateTime to int (epoch milliseconds)
- ZonedDateTimeToLocalDateConverter
- Converts ZonedDateTime to LocalDate
- ZonedDateTimeToLocalDateTimeConverter
- Converts ZonedDateTime to LocalDateTime
- ZonedDateTimeToLocalTimeConverter
- Converts ZonedDateTime to LocalTime
- ZonedDateTimeToStringConverter
- Converts ZonedDateTime to String using ISO 8601 format with timezone
- ZonedDateTimeToZoneIdConverter
- Converts ZonedDateTime to ZoneId
- ZoneIdToStringConverter
- Converts ZoneId to String using the zone ID
Exceptions / Errors
- ConversionException
- Exception thrown when a type conversion fails in a ConversionService.
- ConversionFailedException
- Exception thrown when an actual type conversion attempt fails.
- ConverterNotFoundException
- Exception thrown when no suitable converter can be found for a given source and target type.