Merge branch 'serialization'

KStateMachine · Oct 23, 2024 · e598dc8 · e598dc8
2 parents 1384e55 + bd376ca
commit e598dc8
Show file tree

Hide file tree

Showing 38 changed files with 1,077 additions and 161 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 ![KStateMachine](./docs/kstatemachine-logo.png)
 
-![Build and test with Gradle](https://github.com/nsk90/kstatemachine/workflows/Build%20and%20test%20with%20Gradle/badge.svg)
+![Build and test with Gradle](https://github.com/KStateMachine/kstatemachine/workflows/Build%20and%20test%20with%20Gradle/badge.svg)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nsk90_kstatemachine&metric=alert_status)](https://sonarcloud.io/dashboard?id=nsk90_kstatemachine)
 [![codecov](https://codecov.io/gh/nsk90/kstatemachine/branch/master/graph/badge.svg?token=IR2JR43FOZ)](https://codecov.io/gh/nsk90/kstatemachine)
 [![Maven Central Version](https://img.shields.io/maven-central/v/io.github.nsk90/kstatemachine?logo=sonatype)](https://central.sonatype.com/artifact/io.github.nsk90/kstatemachine)
@@ -19,7 +19,7 @@
 [KDoc](https://kstatemachine.github.io/kstatemachine/kdoc/index.html) |
 [Sponsors](#-sponsors) |
 [Quick start](#-quick-start-sample) |
-[Samples](#-samples) | 
+[Samples](#-samples) |
 [Install](#-install) |
 [Contribution](#-contribution) |
 [Support](#-support) |
@@ -29,57 +29,82 @@
 
 # KStateMachine
 
-KStateMachine is a powerful Kotlin Multiplatform library with clean DSL syntax for creating complex [state machines](https://en.wikipedia.org/wiki/Finite-state_machine)
-and [statecharts](https://www.sciencedirect.com/science/article/pii/0167642387900359/pdf) driven by Kotlin Coroutines.
+**KStateMachine** is a powerful **Kotlin Multiplatform** library with clean DSL syntax for creating
+complex [state machines](https://en.wikipedia.org/wiki/Finite-state_machine)
+and [statecharts](https://www.sciencedirect.com/science/article/pii/0167642387900359/pdf) driven by 
+**Kotlin Coroutines**.
 
 ## 🌏 Overview
 
 ### 📦 Integration features
 
 * **[Kotlin DSL](https://kotlinlang.org/docs/type-safe-builders.html#scope-control-dslmarker) syntax** -
   declarative and clear state machine structure. Using without DSL is also possible.
-* **[Kotlin Coroutines](https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#kotlin-coroutines) support** - 
+* **[Kotlin Coroutines](https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#kotlin-coroutines)
+  support** -
   call suspendable functions within the library.
   You can fully use KStateMachine without Kotlin Coroutines dependency if necessary.
 * **[Kotlin Multiplatform](https://kstatemachine.github.io/kstatemachine/pages/multiplatform.html) support**
-* **Zero dependency** - it is written in pure Kotlin, it does not depend on any third party libraries or Android SDK.
+* **Zero dependency** - it is written in pure Kotlin, main library artifact does not depend on any third party libraries
+  or Android SDK.
 
 ### ⚙️ State management features
 
-* **[Event based](https://kstatemachine.github.io/kstatemachine/pages/events.html)** - [transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html) are performed by
+* **[Event based](https://kstatemachine.github.io/kstatemachine/pages/events.html)
+  ** - [transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html) are performed by
   processing
   incoming events
-* **[Reactive](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-states)** - listen for machine, states,
-  [state groups](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-group-of-states) and transitions
+* **[Reactive](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-states)** - listen for
+  machine, states,
+  [state groups](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-group-of-states) and
+  transitions
 * **[Guarded](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#guarded-transitions)
-  and [Conditional transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#conditional-transitions)** - dynamic
+  and [Conditional transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#conditional-transitions)
+  ** - dynamic
   target
   state which is calculated in a moment of event processing depending on application business logic
-* **[Nested states](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#nested-states)** - build hierarchical state machines
+* **[Nested states](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#nested-states)** - build
+  hierarchical state machines
   (statecharts)
-  with [cross-level transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#cross-level-transitions) support
+  with [cross-level transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#cross-level-transitions)
+  support
 * **[Composed (nested) state machines](
   https://kstatemachine.github.io/kstatemachine/pages/states/states.html#composed-nested-state-machines
   )** - use state machines as atomic child states
-* **[Pseudo states](https://kstatemachine.github.io/kstatemachine/pages/states/pseudo_states.html)** for additional logic in machine
+* **[Pseudo states](https://kstatemachine.github.io/kstatemachine/pages/states/pseudo_states.html)** for additional
+  logic in machine
   behaviour
-* **[Typesafe transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/typesafe_transitions.html)** - pass data in
+* **[Typesafe transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/typesafe_transitions.html)
+  ** - pass data in
   typesafe way
   from event to state
-* **[Parallel states](https://kstatemachine.github.io/kstatemachine/pages/states.html#parallel-states)** - avoid a combinatorial
+* **[Parallel states](https://kstatemachine.github.io/kstatemachine/pages/states.html#parallel-states)** - avoid a
+  combinatorial
   explosion of
   states
-* **[Undo transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#undo-transitions)** - navigate back to previous
-  state (like stack based FSMs do)
-* **[Optional argument](https://kstatemachine.github.io/kstatemachine/pages/events.html#event-argument)** passing for events and
+*
+    *
+
+*[Undo transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#undo-transitions)
+** - navigate back to previous
+state (like stack based FSMs do)
+
+* **[Optional argument](https://kstatemachine.github.io/kstatemachine/pages/events.html#event-argument)** passing for
+  events and
   transitions
 * **[Export](https://kstatemachine.github.io/kstatemachine/pages/export.html)** state machine structure
   to [PlantUML](https://plantuml.com/) and [Mermaid](https://mermaid.js.org/) diagrams
-* **[Persist (serialize)](https://kstatemachine.github.io/kstatemachine/pages/persistence.html)**  state machine's active
-  configuration and restore it later
-* **[Testable](https://kstatemachine.github.io/kstatemachine/pages/testing.html)** - run state machine from specified state and enable internal logging
-* **[Well tested](https://github.com/kstatemachine/kstatemachine/tree/master/tests/src/commonTest/kotlin/ru/nsk/kstatemachine)** - all features are covered
-  by tests
+* **[Persist (serialize)](https://kstatemachine.github.io/kstatemachine/pages/persistence.html)**  state machine's
+  active
+  configuration and restore it later. Built-in `kotlinx.serialization` support.
+* **[Testable](https://kstatemachine.github.io/kstatemachine/pages/testing.html)** - run state machine from specified
+  state and enable internal logging
+*
+    *
+
+*[Well tested](https://github.com/kstatemachine/kstatemachine/tree/master/tests/src/commonTest/kotlin/ru/nsk/kstatemachine)
+** - all features are covered
+by tests
 
 ## 📄 Documentation
 
@@ -93,7 +118,7 @@ I highly appreciate that you donate or become a sponsor to support the project.
 If you find this project useful you can support it by:
 
 * Pushing the ⭐ star-button
-* Using ❤️github-sponsors button to see supported donation methods 
+* Using ❤️github-sponsors button to see supported donation methods
 
 ## 🚀 Quick start sample
 
@@ -125,6 +150,7 @@ object SwitchEvent : Event
 sealed class States : DefaultState() {
     object RedState : States()
     object YellowState : States()
+
     // machine finishes when enters [FinalState]
     object GreenState : States(), FinalState
 }
@@ -152,9 +178,9 @@ fun main() = runBlocking {
         addState(YellowState) {
             transition<SwitchEvent>(targetState = GreenState)
         }
-      
+
         addFinalState(GreenState)
-      
+
         onFinished { println("Finished") }
     }
     // you can observe state machine changes using [Flow] along with simple listeners
@@ -168,14 +194,15 @@ fun main() = runBlocking {
 
 ## 🧪 Samples
 
-* [Simple Android 2D shooter game sample](https://github.com/kstatemachine/android-kstatemachine-sample)
+* [Android 2D shooter game sample](https://github.com/kstatemachine/android-kstatemachine-sample)
 
   The library itself does not depend on Android.
 
   <p align="center">
       <img src="https://github.com/kstatemachine/android-kstatemachine-sample/blob/main/images/android-app-sample.gif"
           alt="Android sample app" width="30%" height="30%"/>
   </p>
+* [Compose 2D shooter game sample](https://github.com/KStateMachine/compose-kstatemachine-sample)
 * [Finished state sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedStateSample.kt)
 * [Transition on FinishedEvent sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventSample.kt)
 * [FinishedEvent using with DataState sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventDataStateSample.kt)
@@ -190,6 +217,7 @@ fun main() = runBlocking {
 * [Guarded transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/GuardedTransitionSample.kt)
 * [Cross-level transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/CrossLevelTransitionSample.kt)
 * [Typesafe transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/TypesafeTransitionSample.kt)
+* [Event recording sample](./samples/src/commonMain/kotlin/ru/nsk/samples/SerializationEventRecordingSample.kt)
 * [Complex syntax sample](./samples/src/commonMain/kotlin/ru/nsk/samples/ComplexSyntaxSample.kt)
   shows many syntax variants and library possibilities, so it looks messy
 
@@ -223,11 +251,11 @@ See [CONTRIBUTING](./CONTRIBUTING.md) file.
 I am open to answer you questions and feature requests. Fill free to use any of communication channels to
 give your feedback.
 
-* [Slack channel](https://kotlinlang.slack.com/archives/C07DVAEKLM8) or 
+* [Slack channel](https://kotlinlang.slack.com/archives/C07DVAEKLM8) or
   [GitHub discussions](https://github.com/kstatemachine/kstatemachine/discussions) - best for questions and discussions
 * [GitHub issues](https://github.com/KStateMachine/kstatemachine/issues) - best for bugs and feature requests
 
-If you use some other platforms to ask questions or mention the library, I recommend adding a <ins>link</ins> to this 
+If you use some other platforms to ask questions or mention the library, I recommend adding a <ins>link</ins> to this
 GitHub project or using `#kstatemachine` tag.
 
 ## 🗺️ Roadmap

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,7 +1,7 @@
 plugins {
     kotlin("jvm") version Versions.kotlin apply false
     id("org.jetbrains.dokka") version Versions.kotlinDokka
-    id("org.jetbrains.kotlinx.binary-compatibility-validator") version Versions.kotlinBinaryCompatibilityValidator
+    id("org.jetbrains.kotlinx.binary-compatibility-validator") version Versions.kotlinBinaryCompatibilityValidatorPlugin
 }
 
 group = Versions.libraryMavenCentralGroup

diff --git a/buildSrc/src/main/kotlin/ru/nsk/Versions.kt b/buildSrc/src/main/kotlin/ru/nsk/Versions.kt
@@ -2,12 +2,12 @@ object Versions {
     // library
     const val libraryMavenCentralGroup = "io.github.nsk90"
     const val libraryJitPackGroup = "com.github.nsk90"
-    const val libraryVersion = "0.31.1"
+    const val libraryVersion = "0.32.0"
 
     // tools
-    const val kotlin = "2.0.0"
+    const val kotlin = "2.0.20"
     const val kotlinDokka = "1.9.20"
-    const val kotlinBinaryCompatibilityValidator = "0.16.3"
+    const val kotlinBinaryCompatibilityValidatorPlugin = "0.16.3"
     const val jacocoTool = "0.8.11"
 
     // compatibility
@@ -17,6 +17,7 @@ object Versions {
 
     // dependencies
     const val coroutinesCore = "1.8.1"
+    const val serialization = "1.7.3"
 
     // test dependencies   
     const val mockk = "1.13.11"

diff --git a/buildSrc/src/main/kotlin/ru/nsk/maven-publish.gradle.kts b/buildSrc/src/main/kotlin/ru/nsk/maven-publish.gradle.kts
@@ -50,17 +50,17 @@ publishing {
                 "KStateMachine is a Kotlin DSL library for creating state machines and " +
                         "hierarchical state machines (statecharts)."
             )
-            url.set("https://github.com/nsk90/kstatemachine")
+            url.set("https://github.com/KStateMachine/kstatemachine")
             inceptionYear.set("2020")
 
             issueManagement {
                 system.set("GitHub")
-                url.set("https://github.com/nsk90/kstatemachine/issues")
+                url.set("https://github.com/KStateMachine/kstatemachine/issues")
             }
             licenses {
                 license {
                     name.set("Boost Software License 1.0")
-                    url.set("https://raw.githubusercontent.com/nsk90/kstatemachine/master/LICENSE")
+                    url.set("https://raw.githubusercontent.com/KStateMachine/kstatemachine/master/LICENSE")
                     distribution.set("repo")
                 }
             }
@@ -73,9 +73,9 @@ publishing {
                 }
             }
             scm {
-                url.set("https://github.com/nsk90/kstatemachine")
-                connection.set("scm:git:git://github.com/nsk90/kstatemachine.git")
-                developerConnection.set("scm:git:ssh://[email protected]/nsk90/kstatemachine.git")
+                url.set("https://github.com/KStateMachine/kstatemachine")
+                connection.set("scm:git:git://github.com/KStateMachine/kstatemachine.git")
+                developerConnection.set("scm:git:ssh://[email protected]/KStateMachine/kstatemachine.git")
             }
         }
     }

diff --git a/docs/pages/export.md b/docs/pages/export.md
@@ -41,7 +41,7 @@ println(machine.exportToPlantUml())
 
 Copy/paste resulting output to [Plant UML online editor](http://www.plantuml.com/plantuml/)
 
-See [PlantUML nested states export sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportSample.kt)
+See [PlantUML nested states export sample](https://github.com/KStateMachine/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportSample.kt)
 
 ## Mermaid
 
@@ -60,7 +60,7 @@ println(machine.exportToMermaid())
   to view diagrams directly in IDE for file types: `.mmd` and `.mermaid`.
 * or copy/paste resulting output to [Mermaid live editor](https://mermaid.live/)
 
-See [Mermaid nested states export sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/MermaidExportSample.kt)
+See [Mermaid nested states export sample](https://github.com/KStateMachine/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/MermaidExportSample.kt)
 
 ## Controlling export output
 
@@ -77,5 +77,5 @@ state("State1") {
 }
 ```
 
-See [PlantUML with MetaInfo export sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportWithMetaInfoSample.kt)
+See [PlantUML with MetaInfo export sample](https://github.com/KStateMachine/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportWithMetaInfoSample.kt)
 
diff --git a/docs/pages/install.md b/docs/pages/install.md
@@ -14,12 +14,14 @@ title: Install
 
 KStateMachine is available on `Maven Central` and `JitPack` repositories.
 
-The library consists of 2 components:
+The library consists of the fallowing components (artifacts):
 
-* `kstatemachine` - (mandatory) state machine implementation (depends only on Kotlin Standard library)
-* `kstatemachine-coroutines` - (optional) add-ons for working with coroutines (depends on Kotlin Coroutines library)
+* `kstatemachine` - (mandatory) state machine implementation (depends only on **Kotlin Standard library**)
+* `kstatemachine-coroutines` - (optional) add-ons for working with coroutines (depends on **Kotlin Coroutines library**)
+* `kstatemachine-serialization` - (optional) add-ons for serialization (depends on **Kotlin Serialization library**). 
+  Released in `v0.32.0`
 
-Please note that starting from `v0.22.0` the library switched to Kotlin Multiplatform and artifact naming has changed.
+Please note that starting from `v0.22.0` the library switched to **Kotlin Multiplatform** and artifact naming has changed.
 
 ## Maven Central
 
@@ -31,24 +33,31 @@ dependencies {
     // multiplatform artifacts (starting from 0.22.0)
     implementation("io.github.nsk90:kstatemachine:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization:<Tag>")
     // or JVM/Android artifacts (starting from 0.22.0)
     implementation("io.github.nsk90:kstatemachine-jvm:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-jvm:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-jvm:<Tag>")
     // or iOS artifacts (starting from 0.22.1)
     implementation("io.github.nsk90:kstatemachine-iosarm64:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-iosarm64:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-iosarm64:<Tag>")
 
     implementation("io.github.nsk90:kstatemachine-iosx64:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-iosx64:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-iosx64:<Tag>")
 
     implementation("io.github.nsk90:kstatemachine-iossimulatorarm64:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-iossimulatorarm64:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-iossimulatorarm64:<Tag>")
     // or JS
     implementation("io.github.nsk90:kstatemachine-js:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-js:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-js:<Tag>")
     // or WebAssembly (Wasm)
     implementation("io.github.nsk90:kstatemachine-wasm-js:<Tag>")
     implementation("io.github.nsk90:kstatemachine-coroutines-wasm-js:<Tag>")
+    implementation("io.github.nsk90:kstatemachine-serialization-wasm-js:<Tag>")
 }
 ```
 
@@ -58,6 +67,7 @@ dependencies {
     // multiplatform artifacts
     implementation 'io.github.nsk90:kstatemachine:<Tag>'
     implementation 'io.github.nsk90:kstatemachine-coroutines:<Tag>' // optional
+    implementation 'io.github.nsk90:kstatemachine-serialization:<Tag>' // optional
     // etc..
 }
 ```
@@ -104,6 +114,7 @@ dependencies {
     // note that group is different in second artifact, long group name also works for first artifact but not vise versa
     // it is some strange JitPack behaviour
     implementation("com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>") // optional
+    implementation("com.github.nsk90.kstatemachine:kstatemachine-serialization:<Tag>") // optional
 }
 ```
 
@@ -114,6 +125,7 @@ dependencies {
     // note that group is different in second artifact, long group name also works for first artifact but not vise versa
     // it is some strange JitPack behaviour
     implementation 'com.github.nsk90.kstatemachine:kstatemachine-coroutines:<Tag>' // optional
+    implementation 'com.github.nsk90.kstatemachine:kstatemachine-serialization:<Tag>' // optional
 }
 ```