https://github.com/quebin31/preferences-helper
Minimal add-on library which provides a nicer API for Preferences Datastore
https://github.com/quebin31/preferences-helper
android datastore-android datastore-preferences jetpack jetpack-android kotlin kotlin-android
Last synced: 5 months ago
JSON representation
Minimal add-on library which provides a nicer API for Preferences Datastore
- Host: GitHub
- URL: https://github.com/quebin31/preferences-helper
- Owner: quebin31
- License: mit
- Created: 2022-07-12T03:05:56.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-07-16T15:27:26.000Z (almost 4 years ago)
- Last Synced: 2023-07-13T17:45:59.134Z (almost 3 years ago)
- Topics: android, datastore-android, datastore-preferences, jetpack, jetpack-android, kotlin, kotlin-android
- Language: Kotlin
- Homepage:
- Size: 128 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Preferences Helper
Minimal add-on library that provides a nicer API for [Preferences DataStore](https://developer.android.com/topic/libraries/architecture/datastore#preferences-datastore)
which is more readable and convenient. I tend to write this same wrapper in all my projects and I've got
tired of doing it manually so I decided to make it a library in case anyone else finds it useful.
## Getting started
Just include the following dependency in your Gradle script, no need to add any extra repository
if you're already using the Maven Central repository (which in most cases you'll be using):
```kotlin
implementation("com.quebin31:preferences-helper:1.0.0")
```
For a comprehensive list of examples head to the [Guide](docs/guide.md).
## Increment counter example
In order to see the benefits of using this library let's compare it to Preferences DataStore,
as per the official Preferences DataStore documentation you'd write the following to update a value:
```kotlin
val Context.dataStore by preferencesDatastore(name = "datastore") // top file declaration
suspend fun incrementCounter() {
val keyCounter = intPreferencesKey(name = "counter")
context.dataStore.edit { mutablePreferences ->
val currentValue = mutablePreferences[keyCounter] ?: 0
mutablePreferences[keyCounter] = currentValue + 1
}
}
```
That's a lot of boilerplate just to update a value, compare it to what you'd write if you were using
this library:
```kotlin
val Context.dataStore by preferencesDatastore(name = "datastore") // top file declaration
// Somewhere you have access to the context, perhaps in a `PreferencesManager` that can be injected
// with Hilt
val helper = PreferencesHelper(context.dataStore)
suspend fun incrementCounter() {
val keyCounter = intPreferencesKey(name = "counter")
helper.update(keyCounter, default = 0) { it + 1 }
}
```
## Performance
By calling `PreferencesHelper(datastore)` we're just creating a thin wrapper around our preferences
datastore, all calls are transformed to the operations you'd normally do if you were using the
`edit` function directly, though there's an **important catch**, each function declared in the
`PreferencesHelper` interface is atomic and separated from the others, you don't have to commit
your changes, this has the advantage of providing an easy way to update, save, read or delete a value
in very few lines.
However, the disadvantage is that doing multiple separate atomic operations is too expensive, each time
a value in the internal data is updated the whole preferences map is updated, the solution to this is
using the `batch` operation whenever you want to update multiple values at once in a single place,
this is pretty similar to using `edit` but with the benefit of having scoped operations identical to the
ones found in the `PreferencesHelper` interface:
### Example
Instead of doing this 3 separate atomic operations:
```kotlin
helper.save(keyA, 3)
helper.delete(keyB)
helper.update(keyC, default = 0) { it + 1 }
```
You can use `batch` to reduce the number of atomic operations from 3 to 1:
```kotlin
helper.batch { // single transaction
save(keyA, 3)
delete(keyB)
update(keyC, default = 0) { it + 1 }
}
```
## LICENSE
This crate is licensed under the terms of the MIT License.
See [LICENSE](LICENSE) to see the full text.