🎯 Meta Field Support #

• NEW: Added optional meta field support in error messages
  • ErrorMessageEntity.meta - nullable Map<String, dynamic> for dynamic error metadata
  • Backend can send or omit meta field with arbitrary data structure
  • No default empty object - null when not provided by backend
• ADDED: Type-safe meta accessor methods:
  • metaInt(String key) - safely get integer values
  • metaDouble(String key) - safely get double values
  • metaStr(String key) - safely get string values
  • metaBool(String key) - safely get boolean values
  • metaMap(String key) - safely get nested map values
• ADDED: Template interpolation with interpolate(String template) method
  • Replaces {key} placeholders with values from meta
  • Example: "Min {min}, max {max}" → "Min 8, max 20"
• UPDATED: toString() method includes meta field
• TESTED: 15 new test cases covering all meta scenarios

📚 Migration Guide from v0.2.0 #

• Fully backward compatible - no changes required for existing code
• meta field is null for responses without metadata
• Use new accessor methods for type-safe meta value extraction
• See example/meta_usage_guide.md for detailed usage examples

✅ Use Cases #

• Validation errors with min/max constraints
• Product availability with ETA information
• Date format validation with expected/received formats
• Dynamic error parameters for localized messages

🔧 Technical Details #

• meta is parsed only if present and is a valid Map
• Invalid meta types are treated as null (graceful degradation)
• No schema validation - application handles meta interpretation
• All existing tests (6) continue to pass

🚀 Major API Format Update #

• NEW: Support for simplified API response format
  • Success responses no longer require "data" wrapper (direct JSON response)
  • Error responses still use "errors" field in root
  • Enhanced fromJsonSafe method automatically detects response type
• IMPROVED: Type-safe parsing with ParseResult<T> return types
• ADDED: New test resources for different response formats
• UPDATED: Documentation with new API format examples

📚 Migration Guide from v0.1.0 #

New API Format (Recommended)

• Success responses: Return data directly {"id": 1, "name": "Tom"}
• Error responses: Keep current format {"errors": [...]}
• Library automatically detects response type based on "errors" field presence

Breaking Changes

• fromJsonSafe now returns ParseResult<ApiResponseEntity<T>> instead of direct entity
• Use result.dataOrThrow or result.dataOrNull to access parsed data

⚡ Benefits #

• Cleaner API responses without unnecessary data wrappers
• Better type safety with ParseResult pattern
• Automatic response type detection
• Backward compatible with legacy format

🗑️ Breaking Changes #

• REMOVED: Complete pagination logic and related classes
  • Removed ApiResponsePagination and ApiResponsePaginationEntity
  • Removed Pagination and PaginationEntity classes
  • Removed ParserResponseWithPaginationEntity
  • Simplified ApiParserSuccessResponse (removed pagination field)
• Simplified: API response handling focuses only on data and errors

📚 Migration Guide from v0.0.4 #

• Remove any usage of pagination-related classes
• ApiParserSuccessResponse no longer has pagination field
• All pagination handling should be implemented in application layer

⚠️ Why Removed? #

Pagination logic was removed to keep the library focused on its core responsibility: error parsing and message handling. Pagination is better handled at the application level or in dedicated data layer components.

🚀 Major Enhancements #

Added

• ErrorTarget enum: Strong type safety for error targets (ErrorTarget.field, ErrorTarget.common)
• ParseResult: Comprehensive result handling for safer parsing operations
• ApiParserConfig: Flexible configuration system with predefined environments
  • ApiParserConfig.production: Minimal logging, graceful error handling
  • ApiParserConfig.debug: Detailed logging for development
  • ApiParserConfig.testing: Strict validation for tests
• Safe parsing methods: fromJsonSafe() variants with detailed error reporting
• Enhanced validation: Automatic validation of error structure and required fields
• Error analysis tools:
  • getUnknownErrorCodes(): Identify unmapped error codes
  • isValidErrorMessage(): Validate error message structure

Enhanced

• Robust error handling: Better exception handling and error reporting
• Type safety: Eliminated magic strings and improved type checking
• Backward compatibility: All existing APIs continue to work
• Documentation: Comprehensive README with migration guide and examples
• Test coverage: Enhanced test suite with new configuration options

Fixed

• JSON parsing errors: Proper validation and error reporting for malformed data
• Null safety: Better handling of null and empty values
• Field validation: Strict validation for field target requirements
• Memory efficiency: Optimized error processing for large error lists

🔧 Breaking Changes #

• ParserMessageEntity.target type changed from String to ErrorTarget
• Direct string comparisons with error targets should be replaced with enum usage

📚 Migration Guide #

1. Replace string comparisons: error.target == "field" → error.target == ErrorTarget.field
2. Add configuration parameter to ApiParser constructor (optional)
3. Consider migrating to fromJsonSafe methods for better error handling

• Added ability to parse lists at the root of JSON responses. Added fromJsonList method to ApiResponseEntity class.

• Added hashCode and operator for ParseMessageEntity and ErrorSourceEntity to compare object when testing bloc(integration tests).

• Initial version with basic API error parsing functionality