From e0ff5e31e974a3fbfb89f83e8eaaec3fbe61fd4d Mon Sep 17 00:00:00 2001 From: fulleni Date: Tue, 23 Sep 2025 20:03:49 +0100 Subject: [PATCH 1/4] chore: remove coverage/lcov.info Removed the lcov.info file from the coverage directory to ensure that test coverage data is not tracked in version control. This helps in maintaining security and reduces the repository size. --- coverage/lcov.info | 43 ------------------------------------------- 1 file changed, 43 deletions(-) delete mode 100644 coverage/lcov.info diff --git a/coverage/lcov.info b/coverage/lcov.info deleted file mode 100644 index a249506..0000000 --- a/coverage/lcov.info +++ /dev/null @@ -1,43 +0,0 @@ -SF:lib\src\kv_storage_service.dart -DA:8,3 -DA:16,1 -DA:18,2 -DA:19,1 -DA:20,3 -DA:22,1 -DA:23,3 -DA:34,2 -DA:42,3 -DA:55,1 -DA:57,3 -DA:58,1 -DA:59,3 -DA:71,3 -DA:80,1 -DA:82,3 -DA:83,1 -DA:84,3 -DA:95,3 -DA:104,1 -DA:106,3 -DA:107,1 -DA:108,3 -DA:119,3 -DA:133,2 -DA:136,0 -DA:141,1 -DA:143,3 -DA:153,2 -DA:158,0 -DA:169,1 -DA:171,5 -LF:32 -LH:30 -end_of_record -SF:lib\src\storage_keys.dart -DA:21,1 -DA:23,1 -DA:25,1 -LF:3 -LH:3 -end_of_record From 37ae9a741e104b7f49b522954b8287544be06e6b Mon Sep 17 00:00:00 2001 From: fulleni Date: Tue, 23 Sep 2025 20:04:05 +0100 Subject: [PATCH 2/4] chore(pubspec): add pubspec.lock file - Generated pubspec.lock file for Dart project - Contains dependencies for various packages used in the project - Ensures consistent dependency versions for better reproducibility --- pubspec.lock | 405 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 pubspec.lock diff --git a/pubspec.lock b/pubspec.lock new file mode 100644 index 0000000..4b38885 --- /dev/null +++ b/pubspec.lock @@ -0,0 +1,405 @@ +# Generated by pub +# See https://dart.dev/tools/pub/glossary#lockfile +packages: + _fe_analyzer_shared: + dependency: transitive + description: + name: _fe_analyzer_shared + sha256: dd3d2ad434b9510001d089e8de7556d50c834481b9abc2891a0184a8493a19dc + url: "https://pub.dev" + source: hosted + version: "89.0.0" + analyzer: + dependency: transitive + description: + name: analyzer + sha256: c22b6e7726d1f9e5db58c7251606076a71ca0dbcf76116675edfadbec0c9e875 + url: "https://pub.dev" + source: hosted + version: "8.2.0" + args: + dependency: transitive + description: + name: args + sha256: d0481093c50b1da8910eb0bb301626d4d8eb7284aa739614d2b394ee09e3ea04 + url: "https://pub.dev" + source: hosted + version: "2.7.0" + async: + dependency: transitive + description: + name: async + sha256: "758e6d74e971c3e5aceb4110bfd6698efc7f501675bcfe0c775459a8140750eb" + url: "https://pub.dev" + source: hosted + version: "2.13.0" + boolean_selector: + dependency: transitive + description: + name: boolean_selector + sha256: "8aab1771e1243a5063b8b0ff68042d67334e3feab9e95b9490f9a6ebf73b42ea" + url: "https://pub.dev" + source: hosted + version: "2.1.2" + cli_config: + dependency: transitive + description: + name: cli_config + sha256: ac20a183a07002b700f0c25e61b7ee46b23c309d76ab7b7640a028f18e4d99ec + url: "https://pub.dev" + source: hosted + version: "0.2.0" + collection: + dependency: transitive + description: + name: collection + sha256: "2f5709ae4d3d59dd8f7cd309b4e023046b57d8a6c82130785d2b0e5868084e76" + url: "https://pub.dev" + source: hosted + version: "1.19.1" + convert: + dependency: transitive + description: + name: convert + sha256: b30acd5944035672bc15c6b7a8b47d773e41e2f17de064350988c5d02adb1c68 + url: "https://pub.dev" + source: hosted + version: "3.1.2" + coverage: + dependency: transitive + description: + name: coverage + sha256: "5da775aa218eaf2151c721b16c01c7676fbfdd99cebba2bf64e8b807a28ff94d" + url: "https://pub.dev" + source: hosted + version: "1.15.0" + crypto: + dependency: transitive + description: + name: crypto + sha256: "1e445881f28f22d6140f181e07737b22f1e099a5e1ff94b0af2f9e4a463f4855" + url: "https://pub.dev" + source: hosted + version: "3.0.6" + file: + dependency: transitive + description: + name: file + sha256: a3b4f84adafef897088c160faf7dfffb7696046cb13ae90b508c2cbc95d3b8d4 + url: "https://pub.dev" + source: hosted + version: "7.0.1" + frontend_server_client: + dependency: transitive + description: + name: frontend_server_client + sha256: f64a0333a82f30b0cca061bc3d143813a486dc086b574bfb233b7c1372427694 + url: "https://pub.dev" + source: hosted + version: "4.0.0" + glob: + dependency: transitive + description: + name: glob + sha256: c3f1ee72c96f8f78935e18aa8cecced9ab132419e8625dc187e1c2408efc20de + url: "https://pub.dev" + source: hosted + version: "2.1.3" + http_multi_server: + dependency: transitive + description: + name: http_multi_server + sha256: aa6199f908078bb1c5efb8d8638d4ae191aac11b311132c3ef48ce352fb52ef8 + url: "https://pub.dev" + source: hosted + version: "3.2.2" + http_parser: + dependency: transitive + description: + name: http_parser + sha256: "178d74305e7866013777bab2c3d8726205dc5a4dd935297175b19a23a2e66571" + url: "https://pub.dev" + source: hosted + version: "4.1.2" + io: + dependency: transitive + description: + name: io + sha256: dfd5a80599cf0165756e3181807ed3e77daf6dd4137caaad72d0b7931597650b + url: "https://pub.dev" + source: hosted + version: "1.0.5" + js: + dependency: transitive + description: + name: js + sha256: "53385261521cc4a0c4658fd0ad07a7d14591cf8fc33abbceae306ddb974888dc" + url: "https://pub.dev" + source: hosted + version: "0.7.2" + logging: + dependency: transitive + description: + name: logging + sha256: c8245ada5f1717ed44271ed1c26b8ce85ca3228fd2ffdb75468ab01979309d61 + url: "https://pub.dev" + source: hosted + version: "1.3.0" + matcher: + dependency: transitive + description: + name: matcher + sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2 + url: "https://pub.dev" + source: hosted + version: "0.12.17" + meta: + dependency: transitive + description: + name: meta + sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394" + url: "https://pub.dev" + source: hosted + version: "1.17.0" + mime: + dependency: transitive + description: + name: mime + sha256: "41a20518f0cb1256669420fdba0cd90d21561e560ac240f26ef8322e45bb7ed6" + url: "https://pub.dev" + source: hosted + version: "2.0.0" + mocktail: + dependency: "direct dev" + description: + name: mocktail + sha256: "890df3f9688106f25755f26b1c60589a92b3ab91a22b8b224947ad041bf172d8" + url: "https://pub.dev" + source: hosted + version: "1.0.4" + node_preamble: + dependency: transitive + description: + name: node_preamble + sha256: "6e7eac89047ab8a8d26cf16127b5ed26de65209847630400f9aefd7cd5c730db" + url: "https://pub.dev" + source: hosted + version: "2.0.2" + package_config: + dependency: transitive + description: + name: package_config + sha256: f096c55ebb7deb7e384101542bfba8c52696c1b56fca2eb62827989ef2353bbc + url: "https://pub.dev" + source: hosted + version: "2.2.0" + path: + dependency: transitive + description: + name: path + sha256: "75cca69d1490965be98c73ceaea117e8a04dd21217b37b292c9ddbec0d955bc5" + url: "https://pub.dev" + source: hosted + version: "1.9.1" + pool: + dependency: transitive + description: + name: pool + sha256: "978783255c543aa3586a1b3c21f6e9d720eb315376a915872c61ef8b5c20177d" + url: "https://pub.dev" + source: hosted + version: "1.5.2" + pub_semver: + dependency: transitive + description: + name: pub_semver + sha256: "5bfcf68ca79ef689f8990d1160781b4bad40a3bd5e5218ad4076ddb7f4081585" + url: "https://pub.dev" + source: hosted + version: "2.2.0" + shelf: + dependency: transitive + description: + name: shelf + sha256: e7dd780a7ffb623c57850b33f43309312fc863fb6aa3d276a754bb299839ef12 + url: "https://pub.dev" + source: hosted + version: "1.4.2" + shelf_packages_handler: + dependency: transitive + description: + name: shelf_packages_handler + sha256: "89f967eca29607c933ba9571d838be31d67f53f6e4ee15147d5dc2934fee1b1e" + url: "https://pub.dev" + source: hosted + version: "3.0.2" + shelf_static: + dependency: transitive + description: + name: shelf_static + sha256: c87c3875f91262785dade62d135760c2c69cb217ac759485334c5857ad89f6e3 + url: "https://pub.dev" + source: hosted + version: "1.1.3" + shelf_web_socket: + dependency: transitive + description: + name: shelf_web_socket + sha256: "3632775c8e90d6c9712f883e633716432a27758216dfb61bd86a8321c0580925" + url: "https://pub.dev" + source: hosted + version: "3.0.0" + source_map_stack_trace: + dependency: transitive + description: + name: source_map_stack_trace + sha256: c0713a43e323c3302c2abe2a1cc89aa057a387101ebd280371d6a6c9fa68516b + url: "https://pub.dev" + source: hosted + version: "2.1.2" + source_maps: + dependency: transitive + description: + name: source_maps + sha256: "190222579a448b03896e0ca6eca5998fa810fda630c1d65e2f78b3f638f54812" + url: "https://pub.dev" + source: hosted + version: "0.10.13" + source_span: + dependency: transitive + description: + name: source_span + sha256: "254ee5351d6cb365c859e20ee823c3bb479bf4a293c22d17a9f1bf144ce86f7c" + url: "https://pub.dev" + source: hosted + version: "1.10.1" + stack_trace: + dependency: transitive + description: + name: stack_trace + sha256: "8b27215b45d22309b5cddda1aa2b19bdfec9df0e765f2de506401c071d38d1b1" + url: "https://pub.dev" + source: hosted + version: "1.12.1" + stream_channel: + dependency: transitive + description: + name: stream_channel + sha256: "969e04c80b8bcdf826f8f16579c7b14d780458bd97f56d107d3950fdbeef059d" + url: "https://pub.dev" + source: hosted + version: "2.1.4" + string_scanner: + dependency: transitive + description: + name: string_scanner + sha256: "921cd31725b72fe181906c6a94d987c78e3b98c2e205b397ea399d4054872b43" + url: "https://pub.dev" + source: hosted + version: "1.4.1" + term_glyph: + dependency: transitive + description: + name: term_glyph + sha256: "7f554798625ea768a7518313e58f83891c7f5024f88e46e7182a4558850a4b8e" + url: "https://pub.dev" + source: hosted + version: "1.2.2" + test: + dependency: "direct dev" + description: + name: test + sha256: "75906bf273541b676716d1ca7627a17e4c4070a3a16272b7a3dc7da3b9f3f6b7" + url: "https://pub.dev" + source: hosted + version: "1.26.3" + test_api: + dependency: transitive + description: + name: test_api + sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55 + url: "https://pub.dev" + source: hosted + version: "0.7.7" + test_core: + dependency: transitive + description: + name: test_core + sha256: "0cc24b5ff94b38d2ae73e1eb43cc302b77964fbf67abad1e296025b78deb53d0" + url: "https://pub.dev" + source: hosted + version: "0.6.12" + typed_data: + dependency: transitive + description: + name: typed_data + sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006 + url: "https://pub.dev" + source: hosted + version: "1.4.0" + very_good_analysis: + dependency: "direct dev" + description: + name: very_good_analysis + sha256: e479fbc0941009262343db308133e121bf8660c2c81d48dd8e952df7b7e1e382 + url: "https://pub.dev" + source: hosted + version: "9.0.0" + vm_service: + dependency: transitive + description: + name: vm_service + sha256: "45caa6c5917fa127b5dbcfbd1fa60b14e583afdc08bfc96dda38886ca252eb60" + url: "https://pub.dev" + source: hosted + version: "15.0.2" + watcher: + dependency: transitive + description: + name: watcher + sha256: "5bf046f41320ac97a469d506261797f35254fa61c641741ef32dacda98b7d39c" + url: "https://pub.dev" + source: hosted + version: "1.1.3" + web: + dependency: transitive + description: + name: web + sha256: "868d88a33d8a87b18ffc05f9f030ba328ffefba92d6c127917a2ba740f9cfe4a" + url: "https://pub.dev" + source: hosted + version: "1.1.1" + web_socket: + dependency: transitive + description: + name: web_socket + sha256: "34d64019aa8e36bf9842ac014bb5d2f5586ca73df5e4d9bf5c936975cae6982c" + url: "https://pub.dev" + source: hosted + version: "1.0.1" + web_socket_channel: + dependency: transitive + description: + name: web_socket_channel + sha256: d645757fb0f4773d602444000a8131ff5d48c9e47adfe9772652dd1a4f2d45c8 + url: "https://pub.dev" + source: hosted + version: "3.0.3" + webkit_inspection_protocol: + dependency: transitive + description: + name: webkit_inspection_protocol + sha256: "87d3f2333bb240704cd3f1c6b5b7acd8a10e7f0bc28c28dcf14e782014f4a572" + url: "https://pub.dev" + source: hosted + version: "1.2.1" + yaml: + dependency: transitive + description: + name: yaml + sha256: b9da305ac7c39faa3f030eccd175340f968459dae4af175130b3fc47e40d76ce + url: "https://pub.dev" + source: hosted + version: "3.1.3" +sdks: + dart: ">=3.9.0 <4.0.0" From bf607a61ab1c1d9133a88c813793ce61cf63f299 Mon Sep 17 00:00:00 2001 From: fulleni Date: Tue, 23 Sep 2025 20:04:10 +0100 Subject: [PATCH 3/4] chore: update .gitignore file - Remove outdated comments and entries - Add coverage/ directory to ignore list - Remove pubspec.lock from ignore list --- .gitignore | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 526da15..171d7ac 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,4 @@ -# See https://www.dartlang.org/guides/libraries/private-files - -# Files and directories created by pub .dart_tool/ .packages build/ -pubspec.lock \ No newline at end of file +coverage/ \ No newline at end of file From 0c0e41862b05e91aa434387a8f45465c45c4370a Mon Sep 17 00:00:00 2001 From: fulleni Date: Tue, 23 Sep 2025 20:06:18 +0100 Subject: [PATCH 4/4] docs(README): rewrite for clarity, conciseness, and completeness - Restructured content for better readability and logical flow - Added feature showcase and core functionality highlights - Included live docs link and main project badge - Updated license information to reflect the package's position within the Flutter News App Toolkit - Improved example code and added missing implementation details --- README.md | 138 +++++++++++------------------------------------------- 1 file changed, 27 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index b57f84c..adb0a17 100644 --- a/README.md +++ b/README.md @@ -1,125 +1,41 @@ -# Key-Value Storage Service Interface +
+ Flutter News App Toolkit Logo +

Key-Value Storage Service

+

The core data models and utilities for the Flutter News App Toolkit.

+
-![coverage: xx](https://img.shields.io/badge/coverage-94-green) -[![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis) -[![License: PolyForm Free Trial](https://img.shields.io/badge/License-PolyForm%20Free%20Trial-blue)](https://polyformproject.org/licenses/free-trial/1.0.0) +

+ coverage: 100% + Live Docs: View + Main Project: Browse +

+This `kv_storage_service` package defines an abstract interface (`KVStorageService`) for key-value storage within the [**Flutter News App Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code). This promotes consistency and allows for interchangeable storage implementations (like SharedPreferences, Hive, secure storage, etc.), ensuring that application logic remains decoupled from the underlying storage mechanism. It provides a standardized way to interact with local data, crucial for managing user preferences, authentication tokens, and other application settings. -A Dart package defining an abstract interface (`KVStorageService`) for key-value storage. This promotes consistency and allows for interchangeable storage implementations (like SharedPreferences, Hive, secure storage, etc.). +## ⭐ Feature Showcase: Flexible & Robust Local Storage -## Features ✨ +This package offers a comprehensive set of features for managing local key-value data. -* Defines a clear contract for basic key-value operations (read, write, delete) for common data types (`String`, `bool`, `int`, `double`). -* Includes a `clearAll` method for removing all entries. -* Provides a `StorageKey` enum to avoid magic strings, promoting type safety. Use the `stringValue` getter for the actual key string. -* Defines a set of custom `StorageException` subclasses (`StorageWriteException`, `StorageReadException`, `StorageDeleteException`, `StorageClearException`, `StorageKeyNotFoundException`, `StorageTypeMismatchException`) to handle specific storage errors. +
+🧱 Core Functionality -## Getting Started 🚀 +### 🚀 Abstract `KVStorageService` Interface +- **`KVStorageService`:** Defines a clear contract for basic key-value operations (read, write, delete) for common data types (`String`, `bool`, `int`, `double`). +- **`clearAll` Method:** Provides a method for efficiently removing all entries from the storage. -### Prerequisites +### 🔐 Type-Safe Key Management +- **`StorageKey` Enum:** Includes a `StorageKey` enum to avoid magic strings, promoting type safety and reducing errors. Use the `stringValue` getter for the actual key string. -* Dart SDK installed. +### 🛡️ Standardized Error Handling +- **Custom `StorageException` Hierarchy:** Defines a comprehensive set of custom `StorageException` subclasses (`StorageWriteException`, `StorageReadException`, `StorageDeleteException`, `StorageClearException`, `StorageKeyNotFoundException`, `StorageTypeMismatchException`) to handle specific storage errors. This ensures predictable and consistent error management across the application layers. -### Installation +### 💉 Implementation Agnostic +- **Interchangeable Implementations:** Designed to be implemented by various storage mechanisms (e.g., `shared_preferences`, `hive`, `flutter_secure_storage`), allowing developers to swap storage solutions without altering application logic. -Add the package to your `pubspec.yaml`: +> **💡 Your Advantage:** You get a meticulously designed, production-quality key-value storage interface that simplifies local data management, ensures type safety, provides robust error handling, and allows for flexible storage implementations. This package accelerates development by providing a solid foundation for local data persistence. -```yaml -dependencies: - kv_storage_service: - git: - url: https://github.com/flutter-news-app-full-source-codet/kv-storage-service.git - ref: main -``` - -### Usage - -1. **Implement the Interface:** Create a concrete class that implements `KVStorageService` using your desired storage mechanism (e.g., `shared_preferences`). - - ```dart - import 'package:kv_storage_service/kv_storage_service.dart'; - import 'package:shared_preferences/shared_preferences.dart'; - - class HtKVStorageSharedPreferences implements KVStorageService { - HtKVStorageSharedPreferences(this._prefs); - - final SharedPreferences _prefs; - - @override - Future writeString({required String key, required String value}) async { - await _prefs.setString(key, value); - } - - @override - Future readString({required String key}) async { - return _prefs.getString(key); - } - - // ... implement other methods (writeBool, readBool, etc.) ... - - @override - Future delete({required String key}) async { - await _prefs.remove(key); - } - - @override - Future clearAll() async { - await _prefs.clear(); - } - } - ``` - -2. **Use the Service:** Inject or provide an instance of your concrete implementation and use the `KVStorageService` interface methods. - - ```dart - import 'package:kv_storage_service/kv_storage_service.dart'; - // import 'package:your_package/your_storage_implementation.dart'; - - Future main() async { - // Obtain an instance of your KVStorageService implementation - // (e.g., using dependency injection or direct instantiation) - // final prefs = await SharedPreferences.getInstance(); - // final storageService = HtKVStorageSharedPreferences(prefs); - - // Example usage: - try { - // Use the stringValue getter for the key - await storageService.writeBool( - key: StorageKey.hasSeenOnboarding.stringValue, - value: true, - ); - final hasSeenOnboarding = await storageService.readBool( - key: StorageKey.hasSeenOnboarding.stringValue, - ); - print('Has seen onboarding: $hasSeenOnboarding'); - } on StorageWriteException catch (e) { - print('Failed to write: ${e.message}, Key: ${e.key}'); - } on StorageReadException catch (e) { - print('Failed to read: ${e.message}, Key: ${e.key}'); - } on StorageTypeMismatchException catch (e) { - print('Type mismatch: ${e.message}, Key: ${e.key}, Expected: ${e.expectedType}, Found: ${e.actualType}'); - } catch (e) { - // Handle other potential exceptions - print('An unexpected error occurred: $e'); - } - } - ``` - -## Error Handling - -The `KVStorageService` methods may throw specific exceptions derived from `StorageException` upon failure: - -* `StorageWriteException`: Thrown by `write*` methods on failure. -* `StorageReadException`: Thrown by `read*` methods on general read failure. -* `StorageDeleteException`: Thrown by `delete` on failure. -* `StorageClearException`: Thrown by `clearAll` on failure. -* `StorageKeyNotFoundException`: May be thrown by `delete` if the key doesn't exist (implementation-dependent). `read*` methods typically return `null` or a default value instead. -* `StorageTypeMismatchException`: Thrown by `read*` methods if the stored data type doesn't match the expected type. - -Implementations should handle these exceptions appropriately (e.g., using `try-catch` blocks). +
## 🔑 Licensing -This package is source-available and licensed under the [PolyForm Free Trial 1.0.0](LICENSE). Please review the terms before use. - -For commercial licensing options that grant the right to build and distribute unlimited applications, please visit the main [**Flutter News App - Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code) organization. +This `kv_storage_service` package is an integral part of the [**Flutter News App Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code). For comprehensive details regarding licensing, including trial and commercial options for the entire toolkit, please refer to the main toolkit organization page.