flutter_shared_utilities 1.0.10

A comprehensive Flutter utilities package with extensions, models, and utility functions.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.10

• Improve README file

1.0.9

Added

• Safe URL Launcher Utility: Comprehensive URL launching utility with advanced safety features

  • SafeUrlLauncher.launch() - Safe URL launching with fallback mode support
    • Preferred mode with automatic fallback (defaults: externalApplication → inAppWebView)
    • Comprehensive error handling and validation
    • Support for custom web-only window names
  • SafeUrlLauncher.launchWithFeedback() - URL launching with user feedback via SnackBar
    • Automatic error message display on launch failure
    • Context safety with mounted widget checking
    • Customizable error messages
    • Graceful handling of null contexts
  • SafeUrlLauncher.launchWebUrl() - Specialized web URL launching
  • SafeUrlLauncher.launchEmail() - Email launching with pre-filled content
    • Support for recipient, subject, and body parameters
    • Proper URL encoding for special characters
    • Safe parameter validation
  • SafeUrlLauncher.launchPhone() - Phone dialer launching with number cleaning
  • SafeUrlLauncher.launchSms() - SMS launching with pre-filled messages
  • SafeUrlLauncher.isValidUrl() - Public URL validation method
    • Validates HTTP/HTTPS URLs with authority checking
    • Supports special schemes (mailto, tel, sms)
    • Comprehensive format validation
  • SafeUrlLauncher.canLaunch() - Check if URL can be launched without actually launching

• Enhanced URL Validation: Intelligent URL scheme validation

  • HTTP/HTTPS URLs require valid authority (domain)
  • Special schemes (mailto, tel, sms) validated by scheme presence
  • Other schemes validated by authority or path presence
  • Robust error handling for malformed URLs

• Phone Number Processing: Smart phone number handling

  • Automatic cleaning of phone numbers (removes formatting)
  • Support for international numbers with + prefix
  • Validation for reasonable phone number lengths (7-15 digits)

• Comprehensive Test Coverage: Added complete test suite for SafeUrlLauncher

  • URL validation tests for all supported schemes
  • Edge case handling and malformed input testing
  • Phone number cleaning and validation tests
  • Email format validation testing

Dependencies

• Added: url_launcher: ^6.3.1 - For URL launching functionality
• Added: flutter/material.dart import - For SnackBar user feedback

Technical Features

• Fallback Mechanism: Automatic fallback between launch modes for better reliability
• Context Safety: Built-in checks for widget lifecycle and mounted state
• Error Resilience: Comprehensive exception handling with debug logging
• Type Safety: Full null safety compliance with safe type checking
• Logging Integration: Uses existing SafeDebugLog for consistent error reporting
• Material Integration: Native Flutter Material Design SnackBar support

Developer Experience

• Flexible API: Multiple convenience methods for different URL types
• Safe Defaults: Sensible default parameters for common use cases
• Clear Documentation: Comprehensive inline documentation with examples
• Return Values: Boolean returns for success/failure tracking
• Error Feedback: Built-in user feedback system for failed launches

1.0.8

Added

• Safe SetState Extensions: Comprehensive setState safety utilities for StatefulWidget classes

  • safeSetState(VoidCallback fn) - Basic safe setState with mounted check
  • safeSetStateAsync(VoidCallback fn) - Safe setState for async operations
  • safeSetStateDelayed(Duration delay, VoidCallback fn) - Safe setState with delay
  • safeRebuild() - Safe widget rebuild without state changes
  • All methods return bool indicating success/failure
  • Prevents the common Flutter error: "setState() called after dispose()"
  • Includes proper exception handling with debug logging
  • Works with any State<T> class through extension methods

• Widget Extensions Structure: New organized extension structure

  • lib/src/extensions/widget/state_extensions.dart - State utility extensions
  • lib/src/extensions/widget/widget.dart - Widget extensions barrel file
  • Updated main extensions export to include widget utilities

Changed

• Enhanced Package Documentation: Updated README with comprehensive Safe SetState examples
  • Added practical usage examples with StatefulWidget
  • Documented all available setState safety methods
  • Updated features list to highlight setState safety utilities
  • Improved quick start guide with widget state management examples

Technical Features

• Mounted State Checking: All setState methods verify widget is mounted before execution
• Error Resilience: Graceful handling of setState exceptions with debug logging
• Async Support: Built-in support for async operations with proper state management
• Delayed Operations: Safe delayed setState operations with automatic cleanup
• Type Safety: Full null safety compliance with comprehensive type checking
• Return Values: Boolean return values for success/failure tracking

1.0.7

• byNameSafe extension for utilities (mainly for enums)

1.0.6

• Support Uint8List type

1.0.5

• Updated lint rules
• Added extra public documentations

1.0.4

Removed

• Interface Classes: Removed abstract interface classes that were not core to the package functionality
  • AppLogger - Application logging interface with debug, info, warning, and error methods
  • ConnectivityService - Network connectivity management interface with internet reachability checks
  • interfaces.dart - Export file for interface classes
  • Complete removal of lib/src/interfaces/ directory

Changed

• Library Exports: Updated main library file (flutter_shared_utilities.dart)
  • Removed export 'src/interfaces/interfaces.dart'; statement
  • Streamlined package to focus on core utilities, extensions, models, and utils

Migration Notes

• Breaking Change: Applications using AppLogger or ConnectivityService interfaces will need to implement their own logging and connectivity abstractions
• Rationale: Removed interface classes to keep the package focused on concrete utilities rather than abstract contracts
• Alternative: Users can copy the interface definitions from version 1.0.3 if needed, or implement their own logging/connectivity abstractions
• No impact on core functionality: extensions, models, parsers, and utility functions remain unchanged

1.0.3

Fixed

• SafeParser Double-Encoding Issue: Fixed critical bug where safeEncodeJson() would double-encode already valid JSON strings
  • Before: SafeParser.safeEncodeJson('"hello"') → "\"hello\"" (double quotes)
  • After: SafeParser.safeEncodeJson('"hello"') → "hello" (correct single encoding)
  • Intelligent JSON detection prevents double-encoding of JSON objects, arrays, and primitives
  • Enhanced _isValidJson() helper method with comprehensive validation
  • Improved fallback logic for malformed JSON strings

Added

• Comprehensive Test Coverage: Added extensive test suites with 78+ new tests

  • test/utils/safe_parser_test.dart - 26 tests covering all SafeParser functionality
  • test/extensions/map/map_parser_extensions_test.dart - 52 tests for MapParserExtensions
  • Round-trip encoding/decoding verification tests
  • Edge case testing (unicode, special characters, deeply nested structures)
  • Error handling and fallback behavior validation
  • Double-encoding prevention verification tests

• Enhanced SafeDecodeJson: Improved JSON decoding with better error handling

  • Smart detection of already-decoded primitive values
  • Enhanced fallback logic for malformed JSON
  • Better handling of quoted strings with escape sequences
  • Graceful return of original string when JSON parsing fails

Changed

• Type Safety Improvements: Enhanced type annotations in test files
  • More specific type expectations (List<Object?> instead of List)
  • Better type checking in map parser extension tests
  • Improved null safety handling throughout tests

Technical Details

• JSON Detection Algorithm: New intelligent JSON validation

  • Detects JSON objects ({} format)
  • Detects JSON arrays ([] format)
  • Detects JSON strings (quoted format)
  • Detects JSON primitives (numbers, booleans, null)
  • Validates actual JSON parseability, not just format

• Test Architecture: Following Flutter best practices

  • Grouped tests by functionality for better organization
  • Comprehensive edge case coverage including unicode and special characters
  • Safe type checking without null force operators or unsafe casting
  • Bounds checking for array access in all test scenarios

Migration Notes

• No breaking changes - all existing functionality preserved
• SafeParser now correctly handles already-encoded JSON without modification
• Enhanced error handling provides better fallback behavior
• Existing code will benefit from the double-encoding fix automatically

1.0.2

Added

• Enhanced Serialization Extensions: Major improvements to fromSerializable<T>() method

  • List<DateTime> support - Convert arrays of ISO strings, timestamps, and DateTime objects
  • List<Duration> support - Convert arrays of microsecond integers, strings, and Duration objects
  • Map<String, DateTime> support - Handle JSON objects with date fields
  • Map<String, Duration> support - Handle configuration objects with time values
  • Early error detection with assert() statements in debug mode
  • Comprehensive type validation with _isSupportedType() helper method

• Safe Conversion Helpers: New helper methods for robust type conversion

  • _safeDateTime() - Handles ISO strings, timestamps, with Unix epoch fallback
  • _safeDuration() - Handles microseconds, strings, with zero duration fallback
  • Graceful error handling for all invalid inputs

• Developer Experience Improvements:

  • Clear, detailed assert error messages guide developers to supported types
  • Immediate feedback during development for unsupported type usage
  • Better documentation in error messages with examples

Changed

• Simplified Architecture: Removed complex recursive type conversion logic

  • Direct type checking for better performance and maintainability
  • Eliminated _extractGenericType() and _extractMapValueType() helper methods
  • Removed _convertToType() recursive method for cleaner code
  • Streamlined error handling with assert-first approach

• Improved Type Safety: Enhanced type checking and conversion

  • Fixed string-to-int conversion to handle decimal strings like "95.5" → 95
  • Better handling of mixed data types in collections
  • More robust JSON string parsing for typed collections

Fixed

• Type casting issues with Map<String, DateTime> and Map<String, Duration>
• Decimal string parsing in _safeInt() method (e.g., "95.5" now converts to 95)
• Eliminated runtime UnsupportedError throws in favor of development-time asserts

Technical Details

• Supported Simple Types: int, double, String, bool, DateTime, Duration, Uri, Object?, dynamic
• Supported List Types: List<int>, List<double>, List<String>, List<bool>, List<DateTime>, List<Duration>, List<Object?>
• Supported Map List Types: List<Map<String, Object?>>, List<Map<String, dynamic>>
• Supported Map Types: Map<String, int>, Map<String, double>, Map<String, String>, Map<String, bool>, Map<String, DateTime>, Map<String, Duration>, Map<String, Object?>, Map<String, dynamic>

Migration Notes

• No breaking changes - all existing functionality preserved
• Assert statements only trigger in debug mode, no impact on production builds
• New DateTime/Duration collection support is additive
• Developers using unsupported nested types will now get immediate feedback via asserts

1.0.1

Added

• Comprehensive documentation and examples in README
• Production-ready package structure
• Badges for pub.dev, license, and Flutter version
• Detailed API reference with code examples
• Contributing guidelines
• Issue and feedback links

Changed

• Updated package description for better clarity
• Enhanced documentation with emojis and better formatting
• Improved code examples with practical use cases

Fixed

• Package naming consistency (flutter_shared_utilities)
• Documentation structure and completeness

1.0.0

Added

• String Extensions: Case-insensitive string operations, JSON validation, and utility methods

  • compareWithoutCase() - Case-insensitive string comparison
  • startsWithIgnoreCase() - Case-insensitive prefix checking
  • containsWithoutCase() - Case-insensitive substring search
  • isNullString, isNullEmpty - Null and empty string checks
  • isJsonObject, isJsonArray, isJsonPrimitive - JSON format validation

• List Extensions: Smart list operations with duplicate prevention

  • insertIfNotExists() - Insert item only if it doesn't exist
  • addAllIfNotExists() - Add multiple items, skipping duplicates
  • removeIfExist() - Remove item if it exists in the list
  • Custom equality checker support for complex objects

• Safe Parser: Robust JSON parsing with error handling

  • safeEncodeJson() - Safe JSON encoding with error handling
  • safeDecodeJson() - Safe JSON decoding with validation
  • parseIterable() - Type-safe iterable parsing

• Base Data Model: Abstract class for consistent data handling

  • fromMap() - Convert Map to model instance
  • toMap() - Convert model to Map
  • fromJson() - Convert JSON string to model instance
  • toJson() - Convert model to JSON string
  • Equatable integration for value equality

• Object Serialization Extensions: Safe type conversion utilities

  • fromSerializable<T>() - Safe type conversion with null safety

• Interfaces: Abstract interfaces for common services

  • AppLogger - Application logging interface
  • ConnectivityService - Network connectivity management interface

• Utility Functions: Additional helper utilities

  • safeDebugLog() - Safe debug logging with stack trace support

• Color Extensions: Enhanced color manipulation utilities

• Map Extensions: Safe map parsing and utility functions

• Iterable Extensions: Utility functions for iterable collections

Technical Features

• Full null safety support
• Comprehensive type checking
• Error handling and safe parsing
• Custom lint rules for code quality
• Flutter 3.0+ compatibility
• Dart SDK 3.8.1+ support

Dependencies

• equatable: ^2.0.7 - For value equality
• collection: ^1.19.1 - For collection utilities
• custom_lint: ^0.7.5 - For custom linting rules
• flutter_custom_lints: ^1.0.2 - For Flutter-specific linting