flutter_shared_utilities #

A comprehensive Flutter utilities package that provides essential extensions, models, and utility functions to streamline your Flutter development workflow. This package includes safe parsing utilities, string manipulation extensions, list operations, and more.

✨ Features #

• 🔧 Safe Parsing: Robust JSON parsing with double-encoding prevention and error handling
• 📝 String Extensions: Case-insensitive comparisons, JSON validation, and utility methods
• 📋 List Utilities: Smart list operations with duplicate prevention
• 🎨 Color Extensions: Enhanced color manipulation utilities
• 🗺️ Map Extensions: Safe map parsing and utility functions
• 📊 Base Data Models: Abstract classes for consistent data handling
• 🔌 Interfaces: Logger and connectivity service interfaces
• 🛡️ Type Safety: Full null safety support with comprehensive type checking
• 🧪 Comprehensive Testing: 169 tests with complete coverage including edge cases

📦 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_shared_utilities: ^1.0.1

Then run:

flutter pub get

🚀 Quick Start #

import '../../flutter_shared_utilities.dart';

void main() {
  // String utilities
  String? text = "Hello World";
  bool isNullEmpty = text.isNullEmpty; // false
  bool startsWith = text.startsWithIgnoreCase("hello"); // true

  // Safe JSON parsing with double-encoding prevention
  String jsonString = '{"name": "John", "age": 30}';
  final parsed = SafeParser.safeDecodeJson(jsonString);

  // No double-encoding - already valid JSON preserved
  String alreadyEncoded = SafeParser.safeEncodeJson('"hello"');
  // → '"hello"' (correct, not "\"hello\"")

  // List utilities
  List<String> fruits = ['apple', 'banana'];
  fruits.addAllIfNotExists(['apple', 'orange']); // Only adds 'orange'
}

📚 API Reference #

String Extensions #

StringUtilExtensions

Provides utility methods for string manipulation and validation:

String? text = "Hello World";

// Case-insensitive operations
bool equals = text.compareWithoutCase("hello world"); // true
bool startsWith = text.startsWithIgnoreCase("hello"); // true
bool contains = text.containsWithoutCase("world"); // true

// Null/empty checks
bool isNull = text.isNullString; // false
bool isEmpty = text.isNullEmpty; // false

// JSON validation
bool isObject = '{"key": "value"}'.isJsonObject; // true
bool isArray = '[1, 2, 3]'.isJsonArray; // true
bool isPrimitive = '"string"'.isJsonPrimitive; // true

List Extensions #

ListUtilExtensions

Smart list operations with duplicate prevention:

List<String> items = ['apple', 'banana'];

// Insert if not exists
bool inserted = items.insertIfNotExists('apple', index: 0); // false (already exists)
bool inserted2 = items.insertIfNotExists('orange', index: 1); // true

// Add all if not exists
items.addAllIfNotExists(['apple', 'grape', 'banana']); // Only adds 'grape'

// Remove if exists
bool removed = items.removeIfExist('apple'); // true

Safe Parser #

SafeParser

Robust JSON parsing with error handling and intelligent double-encoding prevention:

// Safe JSON encoding - prevents double-encoding
String encoded = SafeParser.safeEncodeJson({'name': 'John', 'age': 30});
// → '{"name":"John","age":30}'

// Already encoded JSON is preserved (no double-encoding)
String alreadyEncoded = SafeParser.safeEncodeJson('"hello"');
// → '"hello"' (NOT "\"hello\"")

String jsonObject = SafeParser.safeEncodeJson('{"existing": "json"}');
// → '{"existing": "json"}' (preserves valid JSON)

// Safe JSON decoding with fallback handling
Object? decoded = SafeParser.safeDecodeJson('{"name": "John", "age": 30}');
// → Map<String, dynamic>

// Handles malformed JSON gracefully
Object? fallback = SafeParser.safeDecodeJson('{invalid json}');
// → '{invalid json}' (returns original string as fallback)

// Round-trip consistency guaranteed
String original = 'Hello, 世界! 🚀';
String encoded = SafeParser.safeEncodeJson(original);
Object? decoded = SafeParser.safeDecodeJson(encoded);
// original == decoded ✅

Key Features:

• 🛡️ Double-encoding prevention - Intelligently detects already-encoded JSON
• 🌐 Unicode support - Handles special characters and emojis correctly
• 🔄 Round-trip consistency - Encode → Decode operations are symmetric
• 🚨 Graceful error handling - Never crashes, provides sensible fallbacks
• 📝 Comprehensive logging - Debug-friendly error reporting

Base Data Model #

BaseDataModel

Abstract class for consistent data model implementation:

class User extends BaseDataModel<User> {
  final String name;
  final int age;

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

  @override
  User fromMap(Map<String, dynamic> map) {
    return User(
      name: map['name'] as String,
      age: map['age'] as int,
    );
  }

  @override
  Map<String, dynamic> toMap() {
    return {
      'name': name,
      'age': age,
    };
  }

  @override
  List<Object?> get props => [name, age];
}

// Usage
final user = User(name: 'John', age: 30);
String json = user.toJson();
User fromJson = user.fromJson(json);

🔧 Additional Utilities #

Safe Debug Print #

import '../../utils/safe_debug_print.dart';

safeDebugLog('Debug message', stackTrace: StackTrace.current);

Object Serialization Extensions #

// Safe type conversion
String? value = '123';
int? number = value.fromSerializable<int>(); // 123
double? decimal = value.fromSerializable<double>(); // 123.0

🧪 Testing #

The package includes comprehensive tests for all functionality with 169 total tests covering every feature:

Test Coverage #

• ✅ SafeParser Tests (26 tests) - Complete coverage including double-encoding prevention
• ✅ MapParserExtensions Tests (52 tests) - All type conversions and edge cases
• ✅ Serialization Extensions Tests - Complex type handling and validation
• ✅ String Utility Tests - Case-insensitive operations and JSON validation
• ✅ List Utility Tests - Duplicate prevention and smart operations
• ✅ Base Data Model Tests - Model conversion and serialization

Test Quality Standards #

• 🛡️ Safe Type Checking - No null force operators (!) or unsafe casting (as)
• 🔍 Bounds Checking - All array access is bounds-checked
• 🌐 Unicode Testing - Special characters, emojis, and international text
• 🔄 Round-trip Verification - Encode/decode consistency validation
• 🚨 Error Handling - Graceful failure and fallback behavior testing
• 📊 Edge Cases - Empty data, null values, malformed inputs, large datasets

Running Tests #

# Run all tests
flutter test

# Run specific test files
flutter test test/utils/safe_parser_test.dart
flutter test test/extensions/map/map_parser_extensions_test.dart

# Run with coverage
flutter test --coverage

Test Results #

169/169 tests passing ✅
100% test coverage on critical functionality

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License #

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

🐛 Issues and Feedback #

Please file issues and feature requests on the GitHub repository.

📈 Version History #

See CHANGELOG.md for a detailed version history.

🔗 Links #

• Pub.dev Package
• GitHub Repository
• Issue Tracker

Made with ❤️ for the Flutter community