Option | extension methods simplifying work

lib/hmi_core.dart

@@ -8,8 +8,6 @@ export 'src/core/entities/ds_data_type.dart';
 export 'src/core/entities/ds_status.dart';
 export 'src/core/entities/ds_timestamp.dart';
 export 'src/core/entities/state_constatnts.dart';
-export 'src/core/entities/alarm_colors.dart';
-export 'src/core/entities/state_colors.dart';
 export 'src/core/entities/stacked.dart';
 // RelativeValue
 export 'src/core/relative_value.dart';

lib/hmi_core_entities.dart

@@ -8,6 +8,4 @@ export 'src/core/entities/ds_data_type.dart';
 export 'src/core/entities/ds_status.dart';
 export 'src/core/entities/ds_timestamp.dart';
 export 'src/core/entities/state_constatnts.dart';
-export 'src/core/entities/alarm_colors.dart';
-export 'src/core/entities/state_colors.dart';
 export 'src/core/entities/stacked.dart';

lib/hmi_core_option.dart

@@ -1,3 +1,6 @@
 library hmi_core_option;
 
-export 'src/core/option/option.dart';
+export 'src/core/option/option.dart';
+export 'src/core/option/option_extract_extension.dart';
+export 'src/core/option/option_transform_extension.dart';
+export 'src/core/option/option_querying_extension.dart';

lib/src/app_settings/app_settings.dart

@@ -1,11 +1,20 @@
+import 'dart:convert';
 import 'package:hmi_core/src/core/error/failure.dart';
 import 'package:hmi_core/src/core/json/json_map.dart';
 import 'package:hmi_core/src/core/log/log.dart';
-import 'package:hmi_core/src/core/result/result.dart';
+import 'package:hmi_core/hmi_core_text_file.dart';
+import 'package:hmi_core/src/core/result/result_transform_extension.dart';
 ///
+/// Stores application settings.
+///
+/// Settings can be accessed for reading and writing by its keys.
+///
+/// For key names prefer to use kebab-case notation, with unique prefixes
+/// for different groups of settings. E.g. `ui-padding`, `ui-font-size`,
+/// `api-host`, `api-port`, etc.
 class AppSettings {
-  static const _log = Log('AppSettings');
-  static final _map = <String, dynamic>{
+  static const _log = Log('AppSettings ');
+  static final _settings = <String, dynamic>{
     'displaySizeWidth': 1024,
     'displaySizeHeight': 768,
     // Place Durations in milliseconds!
@@ -18,25 +27,138 @@ class AppSettings {
     'floatingActionButtonSize': 60.0,
     'floatingActionIconSize': 45.0,
   };
+  static final _isWritable = <String, bool>{};
+  static TextFile _store = const TextFile.path('stored_settings.json');
+  ///
+  /// Initializes app settings with [readOnly] and [writable] settings.
+  ///
+  /// [readOnly] settings are accessible for reading only.
   ///
-  static Future<void> initialize({JsonMap<dynamic>? jsonMap}) async {
-    if (jsonMap != null) {
-      await jsonMap.decoded
-        .then((result) => switch(result) {
-          Ok(value: final map) => _map.addAll(map),
-          Err() => _log.warning('Failed to initialize app settings from file.'),
-        });
+  /// [writable] settings are accessible for reading and updating (writing).
+  ///
+  /// [store] file is used to write and restore [writable] settings.
+  /// If not passed, file with path `stored_settings.json` will be used
+  /// by default.
+  static Future<void> initialize({
+    JsonMap<dynamic> readOnly = const JsonMap.empty(),
+    JsonMap<dynamic> writable = const JsonMap.empty(),
+    TextFile? store,
+  }) async {
+    if (store != null) {
+      _store = store;
     }
+    _log.info('Initializing read-only app settings...');
+    await _parseSettings(
+      readOnly,
+      onSettingParsed: (entry) {
+        if (_settings.containsKey(entry.key)) {
+          _log.warning('Setting with key "${entry.key}" will be overwritten.');
+        }
+        _settings[entry.key] = entry.value;
+        _isWritable[entry.key] = false;
+        _log.info('Added read-only setting "${entry.key}": ${entry.value}.');
+      },
+    );
+    _log.info('Initializing writable app settings...');
+    await _parseSettings(
+      writable,
+      onSettingParsed: (entry) {
+        if (_settings.containsKey(entry.key)) {
+          _log.warning('Setting with key "${entry.key}" will be overwritten.');
+        }
+        _settings[entry.key] = entry.value;
+        _isWritable[entry.key] = true;
+        _log.info('Added writeable setting "${entry.key}": ${entry.value}.');
+      },
+    );
+    _log.info('Restoring writable app settings...');
+    await _parseSettings(
+      JsonMap.fromTextFile(_store),
+      onSettingParsed: (entry) {
+        if (!_canWriteSetting(entry.key)) {
+          _log.warning('Writeable setting with key "${entry.key}" does not exist and was ignored.');
+        } else {
+          _settings[entry.key] = entry.value;
+          _log.info('Restored writeable setting "${entry.key}": ${entry.value}.');
+        }
+      },
+    );
+  }
+  //
+  static Future<void> _parseSettings(
+    JsonMap<dynamic> settings, {
+    void Function(MapEntry<String, dynamic>)? onSettingParsed,
+  }) async {
+    final decodedResult = await settings.decoded;
+    decodedResult
+      .inspect((map) {
+        for (final entry in map.entries) {
+          onSettingParsed?.call(entry);
+        }
+      }).inspectErr((error) {
+        _log.warning('Failed to initialize app settings, ${error.message}.');
+      });
+  }
+  //
+  static bool _canWriteSetting(String key) {
+    return _settings.containsKey(key) && _isWritable.containsKey(key) && (_isWritable[key] ?? false);
   }
   ///
-  static dynamic getSetting(String settingName) {
-    final setting = _map[settingName];
-    if (setting == null) {
-      throw Failure(
-        message: 'Ошибка в методе $AppSettings.getSetting(): Не найдена настройка "$settingName"',
-        stackTrace: StackTrace.current,
-      );
+  /// Returns value of app setting by [key].
+  ///
+  /// Calls [onError] that can return other value based on passed [Failure].
+  static dynamic getSetting(
+    String key, {
+    dynamic Function(Failure err)? onError,
+  }) {
+    if (!_settings.containsKey(key)) {
+      final err = Failure('$AppSettings.getSetting | Not found key "$key"');
+      if (onError != null) {
+        return onError(err);
+      }
+      throw err;
+    }
+    return _settings[key];
+  }
+  ///
+  /// Updates app setting with key [key] to new [value]
+  /// and save it asynchronously to file.
+  ///
+  /// Calls [onSuccess] or [onError] when setting will be updated
+  /// and saved successfully or with error.
+  static Future<void> setSetting(
+    String key,
+    dynamic value, {
+    void Function(Failure error)? onError,
+    void Function()? onSuccess,
+  }) async {
+    if (!_canWriteSetting(key)) {
+      final failure = Failure('AppSettings.setSetting | Setting "$key" - is not writable, can\'t be updated');
+      onError?.call(failure);
+    } else {
+      final writableSettings = _getWritableSettings();
+      writableSettings[key] = value;
+      await _store
+        .write(json.encode(writableSettings)).then(
+          (_) {
+            _settings[key] = value;
+            onSuccess?.call();
+          },
+        ).catchError(
+          (error, stackTrace) {
+            final failure = Failure('AppSettings.setSetting | Failed to save setting "$key", $error.');
+            _log.warning(failure);
+            onError?.call(failure);
+          },
+        );
     }
-    return setting;
+  }
+  //
+  static Map<String, dynamic> _getWritableSettings() {
+    return Map.fromEntries(
+      _settings.entries.where(
+        (entry) => _canWriteSetting(entry.key),
+      ),
+    );
   }
 }

lib/src/app_settings/setting.dart

@@ -1,48 +1,72 @@
 import 'app_settings.dart';
-
+import 'package:hmi_core/src/core/error/failure.dart';
 ///
-/// Holds setting value stored in AppSettings by it name
-/// - value can be returned in int, double or string represantation 
+/// Holds setting value stored in [AppSettings] by it name.
+///
+/// Value can be returned in int, double or string representation.
 class Setting {
   final String _name;
   final double _factor;
+  final dynamic Function(Failure err)? _onError;
+  ///
+  /// Holds setting value stored in [AppSettings] by it [name].
+  ///
+  /// Value can be returned in int, double or string representation.
+  /// [int] and [double] values are multiplied by [factor] before returning.
   ///
-  /// - [name] - the name of value stored in AppSettings
-  /// - [factor] - returned value int or double will by multiplied by factor
+  /// Calls [onError] if getting value from [AppSettings] will fail.
   const Setting(
     String name, {
     double factor = 1.0,
-  }) : 
-    _name = name,
-    _factor = factor;
+    dynamic Function(Failure err)? onError,
+  })  : _name = name,
+        _factor = factor,
+        _onError = onError;
   ///
-  /// 
+  /// Returns [Setting] new instance containing a [value]
   const factory Setting.from(dynamic value) = _SettingValue;
-  /// 
-  /// Returns setting value in int represantation
+  ///
+  /// Returns setting value in [int] representation
   int get toInt {
-    final value = AppSettings.getSetting(_name);
+    final value = AppSettings.getSetting(_name, onError: _onError);
     if (value is int) {
       return _factor == 1 ? value : (value * _factor).toInt();
     }
     return (double.parse('$value') * _factor).toInt();
   }
-  /// 
-  /// Returns setting value in double represantation
+  ///
+  /// Returns setting value in [double] representation
   double get toDouble {
-    final value = AppSettings.getSetting(_name);
+    final value = AppSettings.getSetting(_name, onError: _onError);
     if (value is double) {
       return value * _factor;
     }
     return double.parse('$value') * _factor;
   }
-  /// 
-  /// Returns setting value in string represantation
+  ///
+  /// Updates app setting to new [value] and save it asynchronously to file.
+  ///
+  /// Calls [onSuccess] or [onError] when setting will be updated
+  /// and saved successfully or with error.
+  Future<void> update(
+    dynamic value, {
+    void Function(Failure error)? onError,
+    void Function()? onSuccess,
+  }) async {
+    await AppSettings.setSetting(
+      _name,
+      value,
+      onError: onError,
+      onSuccess: onSuccess,
+    );
+  }
+  ///
+  /// Returns setting value in [String] representation
   @override
-  String toString() => '${AppSettings.getSetting(_name)}';
+  String toString() => '${AppSettings.getSetting(_name, onError: _onError)}';
 }
-
-
+///
+///
 class _SettingValue implements Setting {
   final dynamic _value;
   //
@@ -55,6 +79,9 @@ class _SettingValue implements Setting {
   String get _name => throw UnimplementedError();
   //
   @override
+  dynamic Function(Failure err)? get _onError => throw UnimplementedError();
+  //
+  @override
   double get toDouble {
     final value = _value;
     if (value is double) {
@@ -73,5 +100,14 @@ class _SettingValue implements Setting {
   }
   //
   @override
+  Future<void> update(
+    dynamic value, {
+    void Function(Failure error)? onError,
+    void Function()? onSuccess,
+  }) async {
+    onError?.call(Failure('$runtimeType.update | Cannot update setting created during app runtime'));
+  }
+  //
+  @override
   String toString() => '$_value';
-}
+}

lib/src/core/entities/ds_data_class.dart

@@ -1,3 +1,3 @@
 import 'package:hmi_core/src/core/error/failure.dart';
 
 ///
@@ -33,9 +33,8 @@
   factory DsDataClass.fromString(String value) {
     final dataClass = _valueMapping[value];
     if (dataClass == null) {
-      throw Failure.connection(
-        message: 'Ошибка в методе $DsDataClass.fromString: неизвестный класс комманды "$value"',
-        stackTrace: StackTrace.current,
+      throw Failure(
+        'Ошибка в методе $DsDataClass.fromString: неизвестный класс комманды "$value"',
       );
     }
     return dataClass;

lib/src/core/entities/ds_data_point.dart

@@ -1,3 +1,3 @@
 import 'dart:convert';
 import 'package:hmi_core/src/core/entities/ds_cot.dart';
 import 'package:hmi_core/src/core/entities/ds_data_type.dart';
@@ -76,11 +76,7 @@
     DsCot.reqCon ||
     DsCot.actCon => Ok(this),
     DsCot.reqErr || DsCot.actErr => Err(
-      Failure(
-        message: value, 
-        stackTrace: 
-        StackTrace.current,
-      ),
+      Failure(value),
     )
   };
 }

lib/src/core/entities/ds_data_type.dart

@@ -1,3 +1,3 @@
 import 'package:hmi_core/src/core/error/failure.dart';
 
 enum DsDataType {
@@ -41,9 +41,8 @@
     final lvalue = value.toLowerCase();
     final dataType = _valueMapping[lvalue];
     if (dataType == null) {
-      throw Failure.connection(
-        message: 'Ошибка в методе $DsDataType._extract: неизвестный тип данных $value',
-        stackTrace: StackTrace.current,
+      throw Failure(
+        'Ошибка в методе $DsDataType._extract: неизвестный тип данных $value',
       );
     }
     return dataType;