v0.3.0-beta01

What's Changed

• This release is a major overhaul of the underlying model implementation and also improves the public API. See the migration guide below for adapting the usage.
• Rework JetPref model declaration and implementation (Jetpref v3) by @patrickgold in #22
• Change local time entry declaration from time(...) to localTime(...)
• Change local time serialized format from JSON-formatted object to ISO 8601 Time standard

Full Changelog: v0.2.0...v0.3.0-beta01

Migration guide

Dependency declaration

Check out the updated dependency declaration documentation for 0.3.0-beta01 and newer.

Important

Ensure that KSP is applied as a plugin for codegen, and that the model processor is applied as a KSP dependency.

Model declaration

Change declaration from:

fun examplePreferenceModel() = JetPref.getOrCreatePreferenceModel(AppPrefs::class, ::AppPrefs)

class AppPrefs : PreferenceModel("example-app-preferences") {
// ... entries ...
}

to:

val AppPrefsStore = jetprefDataStoreOf(AppPrefsModel::class)

@Preferences
abstract class AppPrefsModel : PreferenceModel() {
// ... entries ...
}

Important

Without the @Preferences annotation, codegen will not be triggered for the model and you will receive a PreferenceModelNotFoundException exception!

Model initialization in Application class

Change initialization from:

class ExampleApplication : Application() {
    private val prefs by examplePreferenceModel()

    override fun onCreate() {
        super.onCreate()

        // Optionally initialize global JetPref configs. This must be done before
        // any preference datastore is initialized!
        JetPref.configure(
            saveIntervalMs = 500,
            encodeDefaultValues = true,
        )

        // Initialize your datastore here (required)
        prefs.initializeBlocking(this)
    }
}

to:

class ExampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize your datastore here (required)
        runBlocking { // not recommended, better is to use a separately launched scope
            AppPrefsStore.initAndroid(
                context = this@ExampleApplication,
                datastoreName = "example-app-preferences",
            )
        }
    }
}

Important

Ensure that the datastoreName passed is the same as the one previously passed to the PreferenceModel constructor. It is used to locate and load the datastore file from disk!

Model usage

Change usage from:

// Get a reference to the preference model
val prefs by examplePreferenceModel()

// Read a preference value manually
prefs.preferenceName.get()

// Write a preference value manually
prefs.preferenceName.set(value)

// Resets a preference value back to default value (`null` internally)
prefs.preferenceName.reset()

// Observe a preference value which automatically removes observer if the lifecycle stops
prefs.preferenceName.observe(lifecycleOwner) { newValue ->
    // Do something with it
}

// Observe a preference value forever, requires manual removal of observer
prefs.preferenceName.observeForever { newValue ->
    // Do something with it
}

// Observe a preference value as a Jetpack Compose state with automatic disposal
val myPreference by prefs.preferenceName.observeAsState()

to:

// Get a reference to the preference model
val prefs by AppPrefsStore

// Read a preference value manually
prefs.preferenceName.get()

// Write a preference value manually
coroutineScope.launch {
    prefs.preferenceName.set(value)
}

// Resets a preference value back to default value (`null` internally)
coroutineScope.launch {
    prefs.preferenceName.reset()
}

// Get a Kotlin flow, which allows to observe state changes
prefs.preferenceName.asFlow()

// Observe a preference value as a Jetpack Compose state with automatic disposal
// (required datastore-ui module dependency)
val myPreference by prefs.preferenceName.observeAsState()