Mutekt
(Pronunciation: /mjuΛΛteΙͺt/, 'k' is silent)
"Simplify mutating "immutable" state models"
Generates mutable models from immutable model definitions. It's based on Kotlin's Symbol Processor (KSP).
This is inspired from the concept Redux and Immer from JS world that let you write simpler immutable update logic
using "mutating" syntax which helps simplify most reducer implementations.
So you just need to focus on actual development and Mutekt will write boilerplate for you!
Like this
Usage
Try out the example app to see it in action.
1. Apply annotation and generate model
Declare a state model as an interface
and apply @GenerateMutableModel
annotation to it.
Example:
@GenerateMutableModel
interface NotesState {
val isLoading: Boolean
val notes: List<String>
val error: String?
}
// You can also apply annotation `@Immutable` if using for Jetpack Compose UI model.
Once done,
2. Simply mutate and get immutable state
The mutable model can be created with the factory function which is generated with the name of an interface with prefix
Mutable
.
For example, if interface name is ExampleState
then method name for creating mutable model will be
MutableExampleState()
and will have parameters in it which are declared as public properties in the interface.
/**
* Instance of mutable model [MutableNotesState] which is generated with Mutekt.
*/
private val _state = MutableNotesState(isLoading = true, notes = emptyList(), error = null)
fun setLoading() {
_state.isLoading = true
}
fun setNotes() {
_state.update {
isLoading = false
notes = listOf("Lorem Ipsum")
}
}
Note
Use methodupdate{}
on Mutable model instance to mutate multiple fields atomically.
3. Getting reactive immutable value updates
To get immutable instance with reactive state updates, use method asStateFlow()
which returns instance of
StateFlow<T>
.
Whenever any field of Mutable model is updated with new value, this StateFlow gets updated with new immutable state value.
val state: StateFlow<NotesState> = _state.asStateFlow()
Properties of immutable instance implemented by Mutekt:
- Immutable model implementation promises to be truly Immutable i.e. once instance is created, its properties will never change.
-
Implementation is actually a data class under the hood i.e. having
equals()
andhashCode()
already overridden.
Setting up Mutekt in the project
1.1 Enable KSP in module
In order to support code generation at compile time, enable KSP support in the module.
plugins {
id 'com.google.devtools.ksp' version '1.7.10-1.0.6'
}
1.2 Add dependencies
1.2.1 Without Kotlin Multiplatform
In build.gradle
of app module, include this dependency
repositories {
mavenCentral()
}
dependencies {
implementation("dev.shreyaspatil.mutekt:mutekt-core:$mutektVersion")
ksp("dev.shreyaspatil.mutekt:mutekt-codegen:$mutektVersion")
// Include kotlin coroutine to support usage of StateFlow
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
}
1.2.2 With Kotlin Multiplatform
In build.gradle.kts
of project module:
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("dev.shreyaspatil.mutekt:mutekt-core:$mutektVersion")
}
}
}
}
dependencies {
add("kspCommonMainMetadata", "dev.shreyaspatil.mutekt:mutekt-codegen:$mutektVersion")
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
if (name != "kspCommonMainKotlinMetadata") {
dependsOn("kspCommonMainKotlinMetadata")
}
}
You can find the latest version and changelogs in the releases.
1.3 Include generated classes in sources
In order to make IDE aware of generated code, it's important to include KSP generated sources in the project source sets.
Include generated sources as follows:
1.3.1 Without Kotlin Multiplatform
Gradle (Groovy)
kotlin {
sourceSets {
main.kotlin.srcDirs += 'build/generated/ksp/main/kotlin'
test.kotlin.srcDirs += 'build/generated/ksp/test/kotlin'
}
}
Gradle (KTS)
kotlin {
sourceSets.main {
kotlin.srcDir("build/generated/ksp/main/kotlin")
}
sourceSets.test {
kotlin.srcDir("build/generated/ksp/test/kotlin")
}
}
Android (Gradle - Groovy)
android {
applicationVariants.all { variant ->
kotlin.sourceSets {
def name = variant.name
getByName(name) {
kotlin.srcDir("build/generated/ksp/$name/kotlin")
}
}
}
}
Android (Gradle - KTS)
android {
applicationVariants.all {
kotlin.sourceSets {
getByName(name) {
kotlin.srcDir("build/generated/ksp/$name/kotlin")
}
}
}
}
1.3.2 With Kotlin Multiplatform
kotlin {
sourceSets {
val commonMain by getting {
kotlin.srcDirs("build/generated/ksp/metadata/commonMain/kotlin")
}
}
}
See also
π¨βπ» Development
Clone this repository and import in IntelliJ IDEA (any edition) or Android Studio.
Module details
-
mutekt-core
: Contain core annotation and interface for mutekt -
mutekt-codegen
: Includes sources for generating mutekt code with KSP -
example
: Example application which demonstrates usage of this library.
Verify build
- To verify whether project building or not:
./gradlew build
. - To verify code formatting:
./gradlew spotlessCheck
. - To reformat code with Spotless:
./gradlew spotlessApply
.
πββοΈ Contribute
Read contribution guidelines for more information regarding contribution.
π¬ Discuss
Have any questions, doubts or want to present your opinions, views? You're always welcome. You can start discussions.
π License
Copyright 2022 Shreyas Patil
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.