feat: add non-nullable versions of flexible parsing functions with default values

Author: travis

CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.3.7
+
+- Added comprehensive tests for all new features
+
+## 0.3.6
+
+- Added non-nullable versions of flexible functions that return default values instead of null:
+- `flexibleRequiredBoolFromJson`: Returns false if null
+- `flexibleRequiredListFromJson`: Returns empty list if null (alias for flexibleListNotNullFromJson)
+
+## 0.3.5
+
+- Added non-nullable versions of flexible functions that return default values instead of null:
+  - `flexibleRequiredIntFromJson`: Returns 0 if null
+  - `flexibleRequiredDoubleFromJson`: Returns 0.0 if null
+  - `flexibleRequiredStringFromJson`: Returns empty string if null
+
 ## 0.3.4
 
 - Ran dart format on the codebase

README.md

@@ -66,7 +66,7 @@ Add this to your package's `pubspec.yaml` file:
 
 ```yaml
 dependencies:
-  json_son: ^0.3.4 # Or the latest version
+  json_son: ^0.3.7 # Or the latest version
 ```
 
 Then, run `flutter pub get` or `dart pub get`.
@@ -512,6 +512,31 @@ class TimestampInfo {
   - Filters out items that parse to `null`.
   - Returns an empty list if the input is `null` or if all items parse to `null`.
 
+- `int flexibleRequiredIntFromJson(dynamic value)`
+  - Non-nullable version of `flexibleIntFromJson`.
+  - Returns `0` instead of `null` when the input is `null` or cannot be parsed as an integer.
+  - Useful when you need to guarantee a non-null integer value.
+
+- `double flexibleRequiredDoubleFromJson(dynamic value)`
+  - Non-nullable version of `flexibleDoubleFromJson`.
+  - Returns `0.0` instead of `null` when the input is `null` or cannot be parsed as a double.
+  - Useful when you need to guarantee a non-null double value.
+
+- `String flexibleRequiredStringFromJson(dynamic value)`
+  - Non-nullable version of `flexibleStringFromJson`.
+  - Returns an empty string (`""`) instead of `null` when the input is `null`.
+  - Useful when you need to guarantee a non-null string value.
+
+- `bool flexibleRequiredBoolFromJson(dynamic value)`
+  - Non-nullable version of `flexibleBoolFromJson`.
+  - Returns `false` instead of `null` when the input is `null` or cannot be parsed as a boolean.
+  - Useful when you need to guarantee a non-null boolean value.
+
+- `List<T> flexibleRequiredListFromJson<T>(dynamic value, T? Function(dynamic) itemParser)`
+  - Alias for `flexibleListNotNullFromJson` to provide a consistent naming convention.
+  - Returns an empty list if the input is `null` or if all items parse to `null`.
+  - Useful when you need to guarantee a non-null list.
+
 - `List<String>? flexibleCommaSeparatedListFromJson(dynamic value)`
   - Parses comma-separated strings (e.g., "apple, banana, cherry") into `List<String>?`.
   - Trims whitespace from each item and filters out empty strings.

lib/json_son.dart

@@ -23,7 +23,14 @@ export 'src/json_son_extensions.dart';
 export 'src/json_son_validator.dart';
 
 export 'src/json_son_base.dart'
-    show flexibleMapFromJson, flexibleMapNotNullFromJson;
+    show
+        flexibleMapFromJson,
+        flexibleMapNotNullFromJson,
+        flexibleRequiredIntFromJson,
+        flexibleRequiredDoubleFromJson,
+        flexibleRequiredStringFromJson,
+        flexibleRequiredBoolFromJson,
+        flexibleRequiredListFromJson;
 
 /// Parses a [dynamic] value into an [int]?.
 /// Handles `null`, `int`, `double` (truncates), and `String` representations.

lib/src/json_son_base.dart

@@ -12,6 +12,13 @@ int? flexibleIntFromJson(dynamic value) {
   return null; // Fallback for other unexpected types
 }
 
+/// Parses a [dynamic] value into a non-nullable [int].
+/// Similar to [flexibleIntFromJson], but returns 0 instead of null.
+/// Useful when you need to guarantee a non-null int value.
+int flexibleRequiredIntFromJson(dynamic value) {
+  return flexibleIntFromJson(value) ?? 0;
+}
+
 /// Parses a [dynamic] value into a [double]?.
 /// Handles `null`, `double`, `int`, and `String` representations.
 /// An empty string or a string that fails to parse will result in `null`.
@@ -26,6 +33,13 @@ double? flexibleDoubleFromJson(dynamic value) {
   return null; // Fallback for other unexpected types
 }
 
+/// Parses a [dynamic] value into a non-nullable [double].
+/// Similar to [flexibleDoubleFromJson], but returns 0.0 instead of null.
+/// Useful when you need to guarantee a non-null double value.
+double flexibleRequiredDoubleFromJson(dynamic value) {
+  return flexibleDoubleFromJson(value) ?? 0.0;
+}
+
 /// Parses a [dynamic] value into a [bool]?.
 /// Handles `null`, `bool`, `String` (e.g., "true", "false", "1", "0", case-insensitive),
 /// and `int` (1 for true, 0 for false) representations.
@@ -46,6 +60,13 @@ bool? flexibleBoolFromJson(dynamic value) {
   return null; // Fallback for other unexpected types or unhandled values
 }
 
+/// Parses a [dynamic] value into a non-nullable [bool].
+/// Similar to [flexibleBoolFromJson], but returns false instead of null.
+/// Useful when you need to guarantee a non-null boolean value.
+bool flexibleRequiredBoolFromJson(dynamic value) {
+  return flexibleBoolFromJson(value) ?? false;
+}
+
 /// Parses a [dynamic] value into a [String]?.
 /// Handles `null` and `String`. Converts other types (like `int`, `double`, `bool`)
 /// to their string representation using `.toString()`.
@@ -57,6 +78,13 @@ String? flexibleStringFromJson(dynamic value) {
   return value.toString();
 }
 
+/// Parses a [dynamic] value into a non-nullable [String].
+/// Similar to [flexibleStringFromJson], but returns an empty string instead of null.
+/// Useful when you need to guarantee a non-null string value.
+String flexibleRequiredStringFromJson(dynamic value) {
+  return flexibleStringFromJson(value) ?? '';
+}
+
 /// Parses a [dynamic] value into a [num]? (int or double).
 /// Handles `null`, `num` (and its subtypes `int`, `double`), and `String` representations.
 /// An empty string or a string that fails to parse will result in `null`.
@@ -173,6 +201,22 @@ List<T> flexibleListNotNullFromJson<T>(
   return parsedSingleItem != null ? [parsedSingleItem] : <T>[];
 }
 
+/// Alias for [flexibleListNotNullFromJson] to provide a consistent naming convention
+/// with other required functions.
+/// Returns an empty list if the input is null or if parsing results in all nulls.
+///
+/// Example:
+/// ```dart
+/// @JsonKey(fromJson: (v) => flexibleRequiredListFromJson(v, flexibleIntFromJson))
+/// List<int> scores; // Guarantees a List<int>, never null.
+/// ```
+List<T> flexibleRequiredListFromJson<T>(
+  dynamic value,
+  T? Function(dynamic) itemParser,
+) {
+  return flexibleListNotNullFromJson<T>(value, itemParser);
+}
+
 /// Parses comma-separated strings into a list of strings.
 /// Handles `null` input.
 /// If input is already a list, its elements are converted to strings.

pubspec.yaml

@@ -2,7 +2,7 @@ name: json_son
 description: >-
   A Dart utility package providing helper functions to flexibly parse JSON values 
   that might have inconsistent data types (e.g., strings to numbers, strings/numbers to booleans).
-version: 0.3.4
+version: 0.3.7
 homepage: https://github.com/scalecode-solutions/json_son/blob/main/README.md
 repository: https://github.com/scalecode-solutions/json_son
 

test/required_functions_test.dart

@@ -0,0 +1,72 @@
+import 'package:json_son/json_son.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('Required (non-nullable) functions', () {
+    test('flexibleRequiredIntFromJson returns 0 for null', () {
+      expect(flexibleRequiredIntFromJson(null), equals(0));
+    });
+
+    test('flexibleRequiredIntFromJson returns parsed value for valid input',
+        () {
+      expect(flexibleRequiredIntFromJson(42), equals(42));
+      expect(flexibleRequiredIntFromJson('42'), equals(42));
+      expect(flexibleRequiredIntFromJson(42.5), equals(42));
+    });
+
+    test('flexibleRequiredDoubleFromJson returns 0.0 for null', () {
+      expect(flexibleRequiredDoubleFromJson(null), equals(0.0));
+    });
+
+    test('flexibleRequiredDoubleFromJson returns parsed value for valid input',
+        () {
+      expect(flexibleRequiredDoubleFromJson(42.5), equals(42.5));
+      expect(flexibleRequiredDoubleFromJson('42.5'), equals(42.5));
+      expect(flexibleRequiredDoubleFromJson(42), equals(42.0));
+    });
+
+    test('flexibleRequiredStringFromJson returns empty string for null', () {
+      expect(flexibleRequiredStringFromJson(null), equals(''));
+    });
+
+    test('flexibleRequiredStringFromJson returns string for valid input', () {
+      expect(flexibleRequiredStringFromJson('hello'), equals('hello'));
+      expect(flexibleRequiredStringFromJson(42), equals('42'));
+      expect(flexibleRequiredStringFromJson(true), equals('true'));
+    });
+
+    test('flexibleRequiredBoolFromJson returns false for null', () {
+      expect(flexibleRequiredBoolFromJson(null), equals(false));
+    });
+
+    test('flexibleRequiredBoolFromJson returns parsed value for valid input',
+        () {
+      expect(flexibleRequiredBoolFromJson(true), equals(true));
+      expect(flexibleRequiredBoolFromJson('true'), equals(true));
+      expect(flexibleRequiredBoolFromJson(1), equals(true));
+      expect(flexibleRequiredBoolFromJson(false), equals(false));
+      expect(flexibleRequiredBoolFromJson('false'), equals(false));
+      expect(flexibleRequiredBoolFromJson(0), equals(false));
+    });
+
+    test('flexibleRequiredListFromJson returns empty list for null', () {
+      expect(flexibleRequiredListFromJson(null, flexibleIntFromJson), isEmpty);
+    });
+
+    test('flexibleRequiredListFromJson returns parsed list for valid input',
+        () {
+      expect(
+        flexibleRequiredListFromJson([1, 2, 3], flexibleIntFromJson),
+        equals([1, 2, 3]),
+      );
+      expect(
+        flexibleRequiredListFromJson(['1', '2', '3'], flexibleIntFromJson),
+        equals([1, 2, 3]),
+      );
+      expect(
+        flexibleRequiredListFromJson(42, flexibleIntFromJson),
+        equals([42]),
+      );
+    });
+  });
+}