Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/patilshreyas/mutekt
Simplify mutating "immutable" state models (a Kotlin multiplatform library)
https://github.com/patilshreyas/mutekt
android android-library coroutines hacktoberfest immutable jetpack-compose jvm-library kmm kmm-library kotlin kotlin-library kotlin-multiplatform kotlin-multiplatform-library kotlin-multiplatform-mobile model multiplatform mutable redux state-management stateflow
Last synced: 10 days ago
JSON representation
Simplify mutating "immutable" state models (a Kotlin multiplatform library)
- Host: GitHub
- URL: https://github.com/patilshreyas/mutekt
- Owner: PatilShreyas
- License: apache-2.0
- Created: 2022-07-30T15:50:13.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-07-27T14:58:53.000Z (over 1 year ago)
- Last Synced: 2024-10-14T03:43:17.578Z (23 days ago)
- Topics: android, android-library, coroutines, hacktoberfest, immutable, jetpack-compose, jvm-library, kmm, kmm-library, kotlin, kotlin-library, kotlin-multiplatform, kotlin-multiplatform-library, kotlin-multiplatform-mobile, model, multiplatform, mutable, redux, state-management, stateflow
- Language: Kotlin
- Homepage:
- Size: 2.94 MB
- Stars: 254
- Watchers: 8
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
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](/example) 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:
```kotlin
@GenerateMutableModel
interface NotesState {
val isLoading: Boolean
val notes: List
val error: String?
}
// You can also apply annotation `@Immutable` if using for Jetpack Compose UI model.
```
Once done, **π¨Build project** and mutable model will be generated for the immutable definition by KSP.
### 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._
```kotlin
/**
* 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 method `update{}` 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`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/).
Whenever any field of Mutable model is updated with new value, this StateFlow gets updated with new immutable state value.
```kotlin
val state: StateFlow = _state.asStateFlow()
```
#### Properties of immutable instance implemented by Mutekt:
- [x] Immutable model implementation promises to be truly ***Immutable*** i.e. once instance is created, its properties
will never change.
- [x] Implementation is actually a ***data class*** under the hood i.e. having `equals()` and `hashCode()`
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](https://kotlinlang.org/docs/ksp-quickstart.html#use-your-own-processor-in-a-project).
```groovy
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
```groovy
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
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().configureEach {
if (name != "kspCommonMainKotlinMetadata") {
dependsOn("kspCommonMainKotlinMetadata")
}
}
```
_You can find the latest version and changelogs in the [releases](https://github.com/PatilShreyas/mutekt/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)
```groovy
kotlin {
sourceSets {
main.kotlin.srcDirs += 'build/generated/ksp/main/kotlin'
test.kotlin.srcDirs += 'build/generated/ksp/test/kotlin'
}
}
```
Gradle (KTS)
```kotlin
kotlin {
sourceSets.main {
kotlin.srcDir("build/generated/ksp/main/kotlin")
}
sourceSets.test {
kotlin.srcDir("build/generated/ksp/test/kotlin")
}
}
```
Android (Gradle - Groovy)
```groovy
android {
applicationVariants.all { variant ->
kotlin.sourceSets {
def name = variant.name
getByName(name) {
kotlin.srcDir("build/generated/ksp/$name/kotlin")
}
}
}
}
```
Android (Gradle - KTS)
```kotlin
android {
applicationVariants.all {
kotlin.sourceSets {
getByName(name) {
kotlin.srcDir("build/generated/ksp/$name/kotlin")
}
}
}
}
```
#### 1.3.2 With Kotlin Multiplatform
```kotlin
kotlin {
sourceSets {
val commonMain by getting {
kotlin.srcDirs("build/generated/ksp/metadata/commonMain/kotlin")
}
}
}
```
## See also
- [Why Mutekt?](https://github.com/PatilShreyas/mutekt/wiki/Why-Mutekt%3F)
- [Generated code with Mutekt](https://github.com/PatilShreyas/mutekt/wiki/Code-generation-with-Mutekt)
## π¨βπ» 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](CONTRIBUTING.md) 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](https://github.com/PatilShreyas/mutekt/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.
```