Skip to content

Commit 0c0e418

Browse files
fullenifulleni
committed
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
1 parent bf607a6 commit 0c0e418

File tree

1 file changed

+27
-111
lines changed

1 file changed

+27
-111
lines changed

‎README.md‎

Lines changed: 27 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,41 @@
1-
# Key-Value Storage Service Interface
1+
<div align="center">
2+
<img src="https://avatars.githubusercontent.com/u/202675624?s=400&u=dc72a2b53e8158956a3b672f8e52e39394b6b610&v=4" alt="Flutter News App Toolkit Logo" width="220">
3+
<h1>Key-Value Storage Service</h1>
4+
<p><strong>The core data models and utilities for the Flutter News App Toolkit.</strong></p>
5+
</div>
26

3-
![coverage: xx](https://img.shields.io/badge/coverage-94-green)
4-
[![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis)
5-
[![License: PolyForm Free Trial](https://img.shields.io/badge/License-PolyForm%20Free%20Trial-blue)](https://polyformproject.org/licenses/free-trial/1.0.0)
7+
<p align="center">
8+
<img src="https://img.shields.io/badge/coverage-100%25-green?style=for-the-badge" alt="coverage: 100%">
9+
<a href="https://flutter-news-app-full-source-code.github.io/docs/"><img src="https://img.shields.io/badge/LIVE_DOCS-VIEW-slategray?style=for-the-badge" alt="Live Docs: View"></a>
10+
<a href="https://github.com/flutter-news-app-full-source-code"><img src="https://img.shields.io/badge/MAIN_PROJECT-BROWSE-purple?style=for-the-badge" alt="Main Project: Browse"></a>
11+
</p>
612

13+
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.
714

8-
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.).
15+
## ⭐ Feature Showcase: Flexible & Robust Local Storage
916

10-
## Features ✨
17+
This package offers a comprehensive set of features for managing local key-value data.
1118

12-
* Defines a clear contract for basic key-value operations (read, write, delete) for common data types (`String`, `bool`, `int`, `double`).
13-
* Includes a `clearAll` method for removing all entries.
14-
* Provides a `StorageKey` enum to avoid magic strings, promoting type safety. Use the `stringValue` getter for the actual key string.
15-
* Defines a set of custom `StorageException` subclasses (`StorageWriteException`, `StorageReadException`, `StorageDeleteException`, `StorageClearException`, `StorageKeyNotFoundException`, `StorageTypeMismatchException`) to handle specific storage errors.
19+
<details>
20+
<summary><strong>🧱 Core Functionality</strong></summary>
1621

17-
## Getting Started 🚀
22+
### 🚀 Abstract `KVStorageService` Interface
23+
- **`KVStorageService`:** Defines a clear contract for basic key-value operations (read, write, delete) for common data types (`String`, `bool`, `int`, `double`).
24+
- **`clearAll` Method:** Provides a method for efficiently removing all entries from the storage.
1825

19-
### Prerequisites
26+
### 🔐 Type-Safe Key Management
27+
- **`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.
2028

21-
* Dart SDK installed.
29+
### 🛡️ Standardized Error Handling
30+
- **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.
2231

23-
### Installation
32+
### 💉 Implementation Agnostic
33+
- **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.
2434

25-
Add the package to your `pubspec.yaml`:
35+
> **💡 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.
2636
27-
```yaml
28-
dependencies:
29-
kv_storage_service:
30-
git:
31-
url: https://github.com/flutter-news-app-full-source-codet/kv-storage-service.git
32-
ref: main
33-
```
34-
35-
### Usage
36-
37-
1. **Implement the Interface:** Create a concrete class that implements `KVStorageService` using your desired storage mechanism (e.g., `shared_preferences`).
38-
39-
```dart
40-
import 'package:kv_storage_service/kv_storage_service.dart';
41-
import 'package:shared_preferences/shared_preferences.dart';
42-
43-
class HtKVStorageSharedPreferences implements KVStorageService {
44-
HtKVStorageSharedPreferences(this._prefs);
45-
46-
final SharedPreferences _prefs;
47-
48-
@override
49-
Future<void> writeString({required String key, required String value}) async {
50-
await _prefs.setString(key, value);
51-
}
52-
53-
@override
54-
Future<String?> readString({required String key}) async {
55-
return _prefs.getString(key);
56-
}
57-
58-
// ... implement other methods (writeBool, readBool, etc.) ...
59-
60-
@override
61-
Future<void> delete({required String key}) async {
62-
await _prefs.remove(key);
63-
}
64-
65-
@override
66-
Future<void> clearAll() async {
67-
await _prefs.clear();
68-
}
69-
}
70-
```
71-
72-
2. **Use the Service:** Inject or provide an instance of your concrete implementation and use the `KVStorageService` interface methods.
73-
74-
```dart
75-
import 'package:kv_storage_service/kv_storage_service.dart';
76-
// import 'package:your_package/your_storage_implementation.dart';
77-
78-
Future<void> main() async {
79-
// Obtain an instance of your KVStorageService implementation
80-
// (e.g., using dependency injection or direct instantiation)
81-
// final prefs = await SharedPreferences.getInstance();
82-
// final storageService = HtKVStorageSharedPreferences(prefs);
83-
84-
// Example usage:
85-
try {
86-
// Use the stringValue getter for the key
87-
await storageService.writeBool(
88-
key: StorageKey.hasSeenOnboarding.stringValue,
89-
value: true,
90-
);
91-
final hasSeenOnboarding = await storageService.readBool(
92-
key: StorageKey.hasSeenOnboarding.stringValue,
93-
);
94-
print('Has seen onboarding: $hasSeenOnboarding');
95-
} on StorageWriteException catch (e) {
96-
print('Failed to write: ${e.message}, Key: ${e.key}');
97-
} on StorageReadException catch (e) {
98-
print('Failed to read: ${e.message}, Key: ${e.key}');
99-
} on StorageTypeMismatchException catch (e) {
100-
print('Type mismatch: ${e.message}, Key: ${e.key}, Expected: ${e.expectedType}, Found: ${e.actualType}');
101-
} catch (e) {
102-
// Handle other potential exceptions
103-
print('An unexpected error occurred: $e');
104-
}
105-
}
106-
```
107-
108-
## Error Handling
109-
110-
The `KVStorageService` methods may throw specific exceptions derived from `StorageException` upon failure:
111-
112-
* `StorageWriteException`: Thrown by `write*` methods on failure.
113-
* `StorageReadException`: Thrown by `read*` methods on general read failure.
114-
* `StorageDeleteException`: Thrown by `delete` on failure.
115-
* `StorageClearException`: Thrown by `clearAll` on failure.
116-
* `StorageKeyNotFoundException`: May be thrown by `delete` if the key doesn't exist (implementation-dependent). `read*` methods typically return `null` or a default value instead.
117-
* `StorageTypeMismatchException`: Thrown by `read*` methods if the stored data type doesn't match the expected type.
118-
119-
Implementations should handle these exceptions appropriately (e.g., using `try-catch` blocks).
37+
</details>
12038

12139
## 🔑 Licensing
12240

123-
This package is source-available and licensed under the [PolyForm Free Trial 1.0.0](LICENSE). Please review the terms before use.
124-
125-
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.
41+
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.

0 commit comments

Comments
 (0)