PatilShreyas/mutektPublic

NotificationsYou must be signed in to change notification settings
Fork7
Star257

Simplify mutating "immutable" state models (a Kotlin multiplatform library)

License

Apache-2.0 license

257 stars 7 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
.github		.github
example		example
gradle		gradle
kotlin-js-store		kotlin-js-store
mutekt-codegen		mutekt-codegen
mutekt-core		mutekt-core
spotless		spotless
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
mutekt-usage.gif		mutekt-usage.gif
settings.gradle.kts		settings.gradle.kts

Repository files navigation

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 conceptRedux andImmer from JS world that let you write simpler immutable update logicusing "mutating" syntax which helps simplify most reducer implementations.So you just need to focus on actual development andMutekt will write boilerplate for you! 😎

Like this ⬇️️

Usage

Try out theexample app to see it in action.

1. Apply annotation and generate model

Declare a state model as aninterface and apply@GenerateMutableModel annotation to it.

Example:

@GenerateMutableModelinterfaceNotesState {val isLoading:Booleanval notes:List<String>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 prefixMutable.For example, if interface name isExampleState then method name for creating mutable model will beMutableExampleState() 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.*/privateval_state=MutableNotesState(isLoading=true, notes= emptyList(), error=null)funsetLoading() {_state.isLoading=true}funsetNotes() {_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 methodasStateFlow() which returns instance ofStateFlow<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 trulyImmutable i.e. once instance is created, its propertieswill never change.
Implementation is actually adata class under the hood i.e. havingequals() andhashCode()already overridden.

Setting upMutekt 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

Inbuild.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

Inbuild.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 thereleases.

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")    }  }}

👨‍💻 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

Readcontribution guidelines for more information regarding contribution.

💬 Discuss

Have any questions, doubts or want to present your opinions, views? You're always welcome. You canstart discussions.

📝 License

Copyright 2022 Shreyas PatilLicensed 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 athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed 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 andlimitations under the License.