Skip to content

Commit cfa108f

Browse files
hoc081098hoc081098
committed
docs
1 parent 95642a7 commit cfa108f

File tree

2 files changed

+78
-48
lines changed

2 files changed

+78
-48
lines changed

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2019-2021 Petrus Nguyễn Thái Học
3+
Copyright (c) 2019-2023 Petrus Nguyễn Thái Học
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 77 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -23,32 +23,37 @@
2323
- This package provides reactive shared preferences interaction with very little code. It is designed specifically to be used with Flutter and Dart.
2424

2525
## Buy me a coffee
26+
2627
Liked some of my work? Buy me a coffee (or more likely a beer)
2728

28-
[!["Buy Me A Coffee"](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://www.buymeacoffee.com/hoc081098)
29+
<a href="https://www.buymeacoffee.com/hoc081098" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" height=64></a>
2930

3031
## Note
3132

3233
Since version `1.3.4`, this package is an extension of [rx_storage](https://github.com/Flutter-Dart-Open-Source/rx_storage) package.
3334

34-
## More detail about returned `Stream`
35-
- It's a **single-subscription `Stream`** (ie. it can only be listened once).
35+
## More details about the returned `Stream`
36+
37+
- It's a **single-subscription `Stream`** (i.e. it can only be listened once).
3638

37-
- `Stream` will emit the **value (nullable)** or **a `TypeError`** as its first event when it is listen to.
39+
- `Stream` will emit the **value (nullable)** or **a `TypeError`** as its first event when it is listened to.
3840

39-
- It will automatically emit value when value associated with key was changed successfully
40-
(**emit `null`** when value associated with key was `removed` or set to `null`).
41+
- It will **automatically** emit the new value when the value associated with key was changed successfully
42+
(it will also **emit `null`** when value associated with key was `removed` or set to `null`).
4143

4244
- When value read from Storage has a type other than expected type:
4345
- If value is `null`, the `Stream` will **emit `null`** (this occurred because `null` can be cast to any nullable type).
4446
- Otherwise, the `Stream` will **emit a `TypeError`**.
4547

46-
- **Can emit** two consecutive data events that are equal. You should use Rx operator like `distinct` (More commonly known as `distinctUntilChanged` in other Rx implementations) to create an `Stream` where data events are skipped if they are equal to the previous data event.
48+
- **Can emit** two consecutive data events that are equal.
49+
You should use Rx operator like `distinct`
50+
(more commonly known as `distinctUntilChanged` in other Rx implementations)
51+
to create a `Stream` where data events are skipped if they are equal to the previous data event.
4752

4853
```text
49-
Key changed: |----------K1---K2------K1----K1-----K2---------> time
54+
Key changed |----------K1---K2------K1----K1-----K2---------> time
5055
|
51-
Value stream: |-----@----@------------@-----@-----------------> time
56+
Value stream |-----@----@------------@-----@-----------------> time
5257
| ^
5358
| |
5459
| Listen(key=K1)
@@ -65,13 +70,13 @@ In your flutter project, add the dependency to your `pubspec.yaml`
6570

6671
```yaml
6772
dependencies:
68-
...
69-
rx_shared_preferences: ^3.0.0
73+
[...]
74+
rx_shared_preferences: <latest_version>
7075
```
7176
7277
## Usage
7378
74-
### 1. Import and instatiance
79+
### 1. Import and instantiate
7580
7681
- Import `rx_shared_preferences`.
7782

@@ -83,21 +88,21 @@ import 'package:rx_shared_preferences/rx_shared_preferences.dart';
8388

8489
```dart
8590
// via constructor.
86-
final rxPrefs = RxSharedPreferences(await SharedPreferences.getInstance());
87-
final rxPrefs = RxSharedPreferences(SharedPreferences.getInstance()); // await is optional
88-
final rxPrefs = RxSharedPreferences.getInstance(); // default singleton instance
91+
final rxPrefs = RxSharedPreferences(await SharedPreferences.getInstance()); // use await
92+
final rxPrefs = RxSharedPreferences(SharedPreferences.getInstance()); // await is optional
93+
final rxPrefs = RxSharedPreferences.getInstance(); // default singleton instance
8994
9095
// via extension.
91-
final rxPrefs = (await SharedPreferences.getInstance()).rx;
96+
final rxPrefs = (await SharedPreferences.getInstance()).rx; // await is required
9297
```
9398

9499
> NOTE: When using `RxSharedPreferences.getInstance()` and extension `(await SharedPreferences.getInstance()).rx`,
95100
> to config the logger, you can use `RxSharedPreferencesConfigs.logger` setter.
96101

97102
### 2. Add a logger (optional)
98103

99-
You can add logger optional parameter to `RxSharedPreferences` constructor.
100-
The logger will log messages about operations (such as read, write) and stream events.
104+
You can pass a logger to the optional parameter of `RxSharedPreferences` constructor.
105+
The logger will log messages about operations (such as read, write, ...) and stream events.
101106
This package provides two `RxSharedPreferencesLogger`s:
102107
- `RxSharedPreferencesDefaultLogger`.
103108
- `RxSharedPreferencesEmptyLogger`.
@@ -111,7 +116,7 @@ final rxPrefs = RxSharedPreferences(
111116
```
112117

113118
> NOTE: To disable logging when running in release mode, you can pass `null` or `const RxSharedPreferencesEmptyLogger()`
114-
> to `RxSharedPreferences` constructor or use `RxSharedPreferencesConfigs.logger` setter.
119+
> to `RxSharedPreferences` constructor, or use `RxSharedPreferencesConfigs.logger` setter.
115120

116121
> NOTE: To prevent printing `↓ Disposed successfully → DisposeBag#...`.
117122
> ```dart
@@ -120,14 +125,15 @@ final rxPrefs = RxSharedPreferences(
120125
> DisposeBagConfigs.logger = null;
121126
> }
122127
> ```
128+
123129
### 3. Select stream and observe
124130

125-
- Then, just listen `Stream`, transform `Stream` through operators such as (`map`, `flatMap`, etc...).
126-
- If you need listen to this `Stream` many times, you can use broadcast operators such as `share`, `shareValue`, `publish`, `publishValue`, etc...
131+
- Then, just listen `Stream`s, transform `Stream`s through operators such as `map`, `flatMap`, etc...
132+
- If you need to listen to the `Stream` many times, you can use broadcast operators such as `share`, `shareValue`, `publish`, `publishValue`, etc...
127133

128134
```dart
129135
// Listen
130-
rxPrefs.getStringListStream('KEY_LIST').listen(print); // [*]
136+
rxPrefs.getStringListStream('KEY_LIST').listen(print); // [*]
131137
132138
// Broadcast stream
133139
rxPrefs.getStringListStream('KEY_LIST').share();
@@ -141,27 +147,33 @@ rxPrefs.getIntStream('KEY_INT')
141147
...
142148
143149
// must **use same rxPrefs** instance when set value and select stream
144-
await rxPrefs.setStringList('KEY_LIST', ['Cool']); // [*] will print ['Cool']
150+
await rxPrefs.setStringList('KEY_LIST', ['Cool']); // [*] will print ['Cool']
145151
```
146152

147-
- In the previous example we re-used the RxSharedPreferences object `rxPrefs` for all writing operations. All writing operations must go through this object in order to correctly notify subscribers.
153+
- In the previous example, we re-used the `RxSharedPreferences` object `rxPrefs` for all operations.
154+
All operations must go through this object in order to correctly notify subscribers.
155+
Basically, you must use the same `RxSharedPreferences` instance when set value and select stream.
148156

149-
- In Flutter, you:
150-
- Can create global `RxSharedPreferences` instance.
157+
- In a Flutter app, you can:
158+
- Create a global `RxSharedPreferences` instance.
151159

152-
- Can use default singleton instance `RxSharedPreferences.getInstance()`
160+
- Use the default singleton instance via `RxSharedPreferences.getInstance()`.
153161

154-
- Can use `InheritedWidget`/`Provider` to provide a `RxSharedPreferences` instance (create it in `main` function) for all widgets (recommended).
155-
See [example/main](https://github.com/hoc081098/rx_shared_preferences/blob/86ae13abf0bcff995d0d99c54b11b103142a257e/example/lib/main.dart#L18).
162+
- Use `InheritedWidget`/`Provider` to provide a `RxSharedPreferences` instance (create it in `main` function) for all widgets (recommended).
163+
See [example/main](https://github.com/hoc081098/rx_shared_preferences/blob/95642a7fe8e8e0ad4579d7ae084aec9a10fe6dff/example/lib/main.dart#L17).
156164

157165
```dart
158166
// An example for wrong usage.
167+
159168
rxPrefs1.getStringListStream('KEY_LIST').listen(print); // [*]
160169
161-
rxPrefs2.setStringList('KEY_LIST', ['Cool']); // [*] will not print anything
170+
rxPrefs2.setStringList('KEY_LIST', ['Cool']); // [*] will not print anything,
171+
// because rxPrefs1 and rxPrefs2 are different instances.
162172
```
163173

164-
- `Stream`s APIs (via extension methods).
174+
### 4. Stream APIs and RxStorage APIs
175+
176+
- All `Stream`s APIs (via extension methods).
165177

166178
```dart
167179
Stream<Object?> getObjectStream(String key, [Decoder<Object?>? decoder]);
@@ -171,26 +183,27 @@ rxPrefs2.setStringList('KEY_LIST', ['Cool']); // [*] will not print anything
171183
Stream<String?> getStringStream(String key);
172184
Stream<List<String>?> getStringListStream(String key);
173185
Stream<Set<String>> getKeysStream();
174-
175-
Future<void> executeUpdateBool(String key, Transformer<bool?> transformer);
176-
Future<void> executeUpdateDouble(String key, Transformer<double?> transformer);
177-
Future<void> executeUpdateInt(String key, Transformer<int?> transformer);
178-
Future<void> executeUpdateString(String key, Transformer<String?> transformer);
179-
Future<void> executeUpdateStringList(String key, Transformer<List<String>?> transformer);
186+
187+
Future<void> updateBool(String key, Transformer<bool?> transformer);
188+
Future<void> updateDouble(String key, Transformer<double?> transformer);
189+
Future<void> updateInt(String key, Transformer<int?> transformer);
190+
Future<void> updateString(String key, Transformer<String?> transformer);
191+
Future<void> updateStringList(String key, Transformer<List<String>?> transformer);
180192
```
181193

182-
- All methods from [RxStorage](https://pub.dev/documentation/rx_storage/latest/rx_storage/RxStorage-class.html) (`RxSharedPreferences` implements `RxStorage`).
194+
- All methods from [RxStorage](https://pub.dev/documentation/rx_storage/latest/rx_storage/RxStorage-class.html)
195+
(because `RxSharedPreferences` implements `RxStorage`).
183196

184197
```dart
185-
Future<void> executeUpdate<T extends Object>(String key, Decoder<T?> decoder, Transformer<T?> transformer, Encoder<T?> encoder);
198+
Future<void> update<T extends Object>(String key, Decoder<T?> decoder, Transformer<T?> transformer, Encoder<T?> encoder);
186199
Stream<T?> observe<T extends Object>(String key, Decoder<T?> decoder);
187200
Stream<Map<String, Object?>> observeAll();
188201
Future<void> dispose();
189202
```
190203

191-
### 4. Get and set methods like to `SharedPreferences`
204+
### 5. Get and set methods likes `SharedPreferences`
192205

193-
- `RxSharedPreferences` is like to `SharedPreferences`, it provides read, write functions (via extension methods).
206+
- `RxSharedPreferences` is like to `SharedPreferences`, it provides `read`, `write` functions (via extension methods).
194207

195208
```dart
196209
Future<Object?> getObject(String key, [Decoder<Object?>? decoder]);
@@ -209,7 +222,8 @@ rxPrefs2.setStringList('KEY_LIST', ['Cool']); // [*] will not print anything
209222
Future<void> setStringList(String key, List<String>? value);
210223
```
211224

212-
- All methods from [Storage](https://pub.dev/documentation/rx_storage/latest/rx_storage/Storage-class.html) (`RxSharedPreferences` implements `Storage`).
225+
- All methods from [Storage](https://pub.dev/documentation/rx_storage/latest/rx_storage/Storage-class.html)
226+
(because `RxSharedPreferences` implements `Storage`).
213227

214228
```dart
215229
Future<bool> containsKey(String key);
@@ -222,17 +236,33 @@ rxPrefs2.setStringList('KEY_LIST', ['Cool']); // [*] will not print anything
222236

223237
### 5. Dispose
224238

225-
You can dispose `RxSharedPreferences` when is no longer needed. Just call `rxPrefs.dispose()`. Usually you call this method on `dispose` of a `State`
239+
You can dispose `RxSharedPreferences` when is no longer needed.
240+
Just call `rxPrefs.dispose()`.
241+
Usually you call this method on `dispose` of a `State`
242+
243+
> NOTE: If you use the default singleton instance (via `RxSharedPreferences.getInstance()`,
244+
> you should **not** call `dispose` method,
245+
> must keep the instance alive for the entire lifetime of the application.
246+
226247

227248
## Example demo
228249

229-
| [Simple authentication app with `BLoC rxdart pattern`](https://github.com/hoc081098/node-auth-flutter-BLoC-pattern-RxDart.git) | [Build ListView from Stream using `RxSharedPreferences`](https://github.com/hoc081098/rx_shared_preferences/tree/master/example) | [Change theme and locale (language) runtime](https://github.com/hoc081098/bloc_rxdart_playground/tree/master/flutter_change_theme) |
230-
| ------------- | ------------- | ------- |
231-
| <img src="https://github.com/hoc081098/node-auth-flutter-BLoC-pattern-RxDart/blob/master/screenshots/Screenshot3.png?raw=true" height="480"> | <img src="https://github.com/hoc081098/rx_shared_preferences/blob/master/example/example.gif?raw=true" height="480"> |<img src="https://github.com/hoc081098/bloc_rxdart_playground/blob/master/flutter_change_theme/Screenshot.gif?raw=true" height="480"> |
250+
| [Simple authentication app with `BLoC rxdart pattern`](https://github.com/hoc081098/node-auth-flutter-BLoC-pattern-RxDart.git) | [Build ListView from Stream using `RxSharedPreferences`](https://github.com/hoc081098/rx_shared_preferences/tree/master/example) | [Change theme and locale (language) runtime](https://github.com/hoc081098/bloc_rxdart_playground/tree/master/flutter_change_theme) |
251+
|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
252+
| <img src="https://github.com/hoc081098/node-auth-flutter-BLoC-pattern-RxDart/blob/master/screenshots/Screenshot3.png?raw=true" height="480"> | <img src="https://github.com/hoc081098/rx_shared_preferences/blob/master/example/example.gif?raw=true" height="480"> | <img src="https://github.com/hoc081098/bloc_rxdart_playground/blob/master/flutter_change_theme/Screenshot.gif?raw=true" height="480"> |
253+
254+
## Features and bugs
255+
256+
Please file feature requests and bugs at the [issue tracker][tracker].
257+
258+
[tracker]: https://github.com/hoc081098/rx_shared_preferences/issues
232259

233260
## License
261+
234262
```text
235-
Copyright (c) 2019-2021 Petrus Nguyễn Thái Học
263+
MIT License
264+
265+
Copyright (c) 2019-2023 Petrus Nguyễn Thái Học
236266
```
237267

238268
## Contributors ✨

0 commit comments

Comments
 (0)