Type Caster #

A lightweight and safe type casting library for Dart that provides flexible type conversion utilities with clear error handling.

Features #

• Support for common Dart types: int, double, String, bool, List, Set
• Global casting functions: tryAs<T>(), asString(), asInt(), etc.

Installation #

Add type_caster to your pubspec.yaml:

dependencies:
  type_caster: ^0.0.4

Then run:

flutter pub get
# or
# dart pub get

Usage #

Basic Type Casting #

import 'package:type_caster/type_caster.dart';

void main() {
  final Object? value = '123';

  // Using global functions
  final int? number = tryInt(value);     // Returns: 123
  final String text = asString(value);    // Returns: "123"
  
  // With fallback values using orElse
  final bool flag = asBool(value, orElse: () => false);  // Returns: false
  
  // Error handling
  try {
    final bool result = asBool('not-a-bool');
  } on CastException catch (e) {
    print(e.toString()); // "Cannot cast String to bool | Source: not-a-bool"
  }
}

List Conversion #

import 'package:type_caster/type_caster.dart';

void main() {
  // From JSON array string
  final numbers = asList<int>('[1,2,3]', itemDecoder: (e) => asInt(e));
  print(numbers); // [1, 2, 3]
  
  // From comma-separated string
  final items = asList<String>('a,b,c');
  print(items); // ["a", "b", "c"]
  
  // From Set to List
  final set = {'1', '2', '3'};
  final list = asList<String>(set);
  print(list); // ["1", "2", "3"]
}

Custom Caster Example #

class User {
  final String? name;
  final int? age;

  User({required this.name, required this.age});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      name: tryString(json['name']),
      age: tryInt(json['age']),
    );
  }
}

API Reference #

Global Functions #

Type Casting

Note: The parsing utilities (tryParse* and parse* methods) are aliases for the corresponding global functions in caster_core.dart, providing a more explicit way to parse various types.

• T? tryAs<T>(dynamic src, {T? Function()? orElse}): Generic type casting
• String asString(dynamic val, {String Function()? orElse})
• String? tryString(dynamic val, {String Function()? orElse})
• num asNum(dynamic val, {num Function()? orElse})
• num? tryNum(dynamic val, {num Function()? orElse})
• int asInt(dynamic val, {int Function()? orElse})
• int? tryInt(dynamic val, {int Function()? orElse})
• double asDouble(dynamic val, {double Function()? orElse})
• double? tryDouble(dynamic val, {double Function()? orElse})
• bool asBool(dynamic val, {bool Function()? orElse})
• bool? tryBool(dynamic val, {bool Function()? orElse})

List Operations

• List<T> asList<T>(dynamic val, {List<T> Function()? orElse, T Function(dynamic)? itemDecoder, String separator = ','})
• List<T>? tryList<T>(dynamic val, {List<T> Function()? orElse, T Function(dynamic)? itemDecoder, String separator = ','})

Parsing Utilities

• String? tryParseString(dynamic value, {String Function()? orElse})
• String parseString(dynamic value, {String Function()? orElse})
• num? tryParseNum(dynamic value, {num Function()? orElse})
• num parseNum(dynamic value, {num Function()? orElse})
• int? tryParseInt(dynamic value, {int Function()? orElse})
• int parseInt(dynamic value, {int Function()? orElse})
• double? tryParseDouble(dynamic value, {double Function()? orElse})
• double parseDouble(dynamic value, {double Function()? orElse})
• bool? tryParseBool(dynamic value, {bool Function()? orElse})
• bool parseBool(dynamic value, {bool Function()? orElse})
• List<T>? tryParseList<T>(dynamic value, {List<T> Function()? orElse, T Function(dynamic)? itemDecoder, String separator = ','})
• List<T> parseList<T>(dynamic value, {List<T> Function()? orElse, T Function(dynamic)? itemDecoder, String separator = ','})

Error Handling #

The library uses CastException for error handling, providing:

• Source value and type information
• Target type information
• Optional custom message
• Optional inner exception
• Colorized error output

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support #

If you find this package useful, please consider giving it a star on GitHub.

For issues and feature requests, please use the issue tracker.