musotec / rekoil

A reactive Kotlin DSL for lightweight state management as an extension of Coroutines

rekoil

Rekoil is a reactive Kotlin API for lightweight state management as an extension of Coroutines.

This is a companion to Kotlin and kotlinx-coroutines past the 1.3.72 release. Multiplatform support is planned, but currently not tested or implemented.

This version is experimental, is likely to change, and is currently only tested on the JVM and Android.

suspend fun main() = rekoilScope {
    val atom1 = atom { "Hello" }.apply {
        subscribe { println(it) }
    }

    atom1.value = "World"
}

This is an unofficial Kotlin implementation of the architecture behind facebookexperimental/Recoil (https://recoiljs.org)

rekoil in use

Check out this example and more.

Motivation

The goal of this project is to simplify the creation and reactive interaction of application components by encapsulating single sources of truth as nodes.
These nodes are lightweight and abstract the boilerplate involved with the communication of updates to the single source of truth across nodes that depend on it.

Documentation

• Changelog
• Basic Guide
  • Atoms
  • Selectors
  • Scopes
  • Differences (from recoil.js)
• Dokka
• Presentations and videos:
  • Official facebook experimental repo
• Facebook Experimental Recoil (Recoil.js) Reference:
  • Recoil website
  • Official facebook experimental repo
  • Recoil: State Management - Dave McCabe (ReactEurope 2020 talk)

Using in your projects

The Rekoil library is published to musotec's bintray repository and linked to JCenter.

👌 Maven

<dependency>
  <groupId>tech.muso.rekoil</groupId>
  <artifactId>rekoil</artifactId>
  <version>0.0.3</version>
</dependency>

Gradle

Add dependencies. (Currently built against Kotlin version 1.3.72)
Note that kotlin-stdlib must be included in your project. However, the kotlinx-coroutines library does not. When this project changes to versions 1.4.0 and higher, the kotlin-stdlib will be included by the coroutines library.

dependencies {
    implementation("tech.muso.rekoil:rekoil:0.0.3")
}

Make sure that you have jcenter() in the list of repositories:

repository {
    jcenter()
}

Android

Add kotlinx-coroutines-android module as dependency when using Rekoil on Android:

implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.7'

Additionally, to prevent leakage of coroutines and channels within this library you should pass an Android CoroutineScope when creating your RekoilScope.

For ViewModelScope, use androidx.lifecycle:lifecycle-viewmodel-ktx:2.1.0-beta01 or higher.
For LifecycleScope, use androidx.lifecycle:lifecycle-runtime-ktx:2.2.0-alpha01 or higher.

Then use as such:

val rekoilScope = RekoilScope(viewModelScope).launch {
    // your rekoil code here
}

Multiplatform

Rekoil only uses the Core modules of kotlinx.coroutines, so that it will be available for Kotlin/JS and Kotlin/Native.

However, due to technical debt, I have not yet tested this. However, if you wish to compile and use on another platform, you should be able to add the necessary dependencies yourself.

The oldest version of Kotlin this source code should be compatible with is version 1.3.20. But versions below 1.3.71 are untested and unsupported. Version 1.3.20 is likely to only work on the JVM.

Planned Updates

Yes