{"id":13537344,"url":"https://github.com/KStateMachine/kstatemachine","last_synced_at":"2025-04-02T04:30:33.143Z","repository":{"id":45554234,"uuid":"296142904","full_name":"KStateMachine/kstatemachine","owner":"KStateMachine","description":"Powerful Kotlin Multiplatform library with clean DSL syntax for creating complex state machines and statecharts driven by Kotlin Coroutines.","archived":false,"fork":false,"pushed_at":"2024-10-24T17:08:42.000Z","size":1915,"stargazers_count":368,"open_issues_count":1,"forks_count":21,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-30T00:48:00.599Z","etag":null,"topics":["android-library","dsl","fsm","fsm-library","hierarchical-state-machine","hsm","kotlin","kotlin-coroutines","kotlin-multiplatform","nested-states","open-source","plantuml","state","state-machine","state-management","statechart","statemachine","transitions"],"latest_commit_sha":null,"homepage":"https://kstatemachine.github.io/kstatemachine/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KStateMachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"kstatemachine","ko_fi":"nskfedotov","custom":"https://yoomoney.ru/to/4100118569686448"}},"created_at":"2020-09-16T20:38:57.000Z","updated_at":"2024-10-27T10:57:42.000Z","dependencies_parsed_at":"2023-11-19T20:24:37.567Z","dependency_job_id":"2f382252-3460-4c07-ae48-4c8cdc4b7177","html_url":"https://github.com/KStateMachine/kstatemachine","commit_stats":{"total_commits":534,"total_committers":7,"mean_commits":76.28571428571429,"dds":0.4325842696629213,"last_synced_commit":"c148de237553652283352a29357ae082a1ca5b4f"},"previous_names":["kstatemachine/kstatemachine"],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KStateMachine%2Fkstatemachine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KStateMachine%2Fkstatemachine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KStateMachine%2Fkstatemachine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KStateMachine%2Fkstatemachine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KStateMachine","download_url":"https://codeload.github.com/KStateMachine/kstatemachine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246756811,"owners_count":20828771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-library","dsl","fsm","fsm-library","hierarchical-state-machine","hsm","kotlin","kotlin-coroutines","kotlin-multiplatform","nested-states","open-source","plantuml","state","state-machine","state-management","statechart","statemachine","transitions"],"created_at":"2024-08-01T09:00:57.878Z","updated_at":"2025-04-02T04:30:33.137Z","avatar_url":"https://github.com/KStateMachine.png","language":"Kotlin","readme":"# KStateMachine\n\n![Build and test with Gradle](https://github.com/KStateMachine/kstatemachine/workflows/Build%20and%20test%20with%20Gradle/badge.svg)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nsk90_kstatemachine\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=nsk90_kstatemachine)\n[![codecov](https://codecov.io/gh/nsk90/kstatemachine/branch/master/graph/badge.svg?token=IR2JR43FOZ)](https://codecov.io/gh/nsk90/kstatemachine)\n[![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)\n[![JitPack](https://img.shields.io/jitpack/version/io.github.nsk90/kstatemachine?style=flat\u0026logo=jitpack\u0026color=brgreen)](https://jitpack.io/#nsk90/kstatemachine)\n[![multiplatform support](https://img.shields.io/badge/multiplatform-jvm%20%7C%20android%20%7C%20ios%20%7C%20js%20%7C%20wasm-brightgreen)](https://kstatemachine.github.io/kstatemachine/#multiplatform)\n\n[![Open Collective](https://img.shields.io/badge/open%20collective-kstatemachine-lightblue?logo=opencollective\u0026style=flat)](https://opencollective.com/kstatemachine)\n[![JetBrains support](https://img.shields.io/badge/JetBrains-support-black?style=flat\u0026logo=jetbrains)](https://jb.gg/OpenSourceSupport)\n[![Mentioned in Awesome Kotlin](https://awesome.re/mentioned-badge.svg)](https://github.com/KotlinBy/awesome-kotlin)\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-kstatemachine-green.svg?style=flat)](https://android-arsenal.com/details/1/8276)\n[![Share on X](https://img.shields.io/badge/twitter-share-white?logo=x\u0026style=flat)](https://twitter.com/intent/tweet?text=I%20like%20KStateMachine%20library%20%0A%0Ahttps%3A%2F%2Fgithub.com%2Fkstatemachine%2Fkstatemachine\u0026hashtags=kstatemachine,kotlin,opensource)\n[![Share on Reddit](https://img.shields.io/badge/reddit-share-red?logo=reddit\u0026style=flat)](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fkstatemachine%2Fkstatemachine\u0026title=I%20like%20KStateMachine%20library)\n[![Slack](https://img.shields.io/badge/slack-kstatemachine-purple?logo=slack\u0026style=flat)](https://kotlinlang.slack.com/archives/C07DVAEKLM8)\n\n![KStateMachine](./docs/kstatemachine-logo.png)\n\n**[Documentation](https://kstatemachine.github.io/kstatemachine) |\n[KDoc](https://kstatemachine.github.io/kstatemachine/kdoc/index.html) |\n[Sponsors](#-sponsors) |\n[Quick start](#-quick-start-sample) |\n[Samples](#-samples) |\n[Install](#-install) |\n[Contribution](#-contribution) |\n[Support](#-support) |\n[Roadmap](#-roadmap) |\n[License](#-license) |\n[Discussions](https://github.com/kstatemachine/kstatemachine/discussions)**\n\n**KStateMachine** is a powerful **Kotlin Multiplatform** library with clean DSL syntax for creating\ncomplex [state machines](https://en.wikipedia.org/wiki/Finite-state_machine)\nand [statecharts](https://www.sciencedirect.com/science/article/pii/0167642387900359/pdf) driven by \n**Kotlin Coroutines**.\n\n## 🌏 Overview\n\n### 📦 Integration features\n\n* **[Kotlin DSL](https://kotlinlang.org/docs/type-safe-builders.html#scope-control-dslmarker) syntax** -\n  declarative and clear state machine structure. Using without DSL is also possible.\n* **[Kotlin Coroutines](https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#kotlin-coroutines)\n  support** -\n  call suspendable functions within the library.\n  You can fully use KStateMachine without Kotlin Coroutines dependency if necessary.\n* **[Kotlin Multiplatform](https://kstatemachine.github.io/kstatemachine/pages/multiplatform.html) support**\n* **Zero dependency** - it is written in pure Kotlin, main library artifact does not depend on any third party libraries\n  or Android SDK.\n\n### ⚙️ State management features\n\n* **[Event based](https://kstatemachine.github.io/kstatemachine/pages/events.html)** - [transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html) are performed by\n  processing\n  incoming events\n* **[Reactive](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-states)** - listen for\n  machine, states,\n  [state groups](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#listen-group-of-states) and\n  transitions\n* **[Guarded](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#guarded-transitions)\n  and [Conditional transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#conditional-transitions)** - dynamic\n  target\n  state which is calculated in a moment of event processing depending on application business logic\n* **[Nested states](https://kstatemachine.github.io/kstatemachine/pages/states/states.html#nested-states)** - build\n  hierarchical state machines\n  (statecharts)\n  with [cross-level transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#cross-level-transitions)\n  support\n* **[Composed (nested) state machines](\n  https://kstatemachine.github.io/kstatemachine/pages/states/states.html#composed-nested-state-machines\n  )** - use state machines as atomic child states\n* **[Pseudo states](https://kstatemachine.github.io/kstatemachine/pages/states/pseudo_states.html)** for additional\n  logic in machine\n  behaviour\n* **[Typesafe transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/typesafe_transitions.html)** - pass data in\n  typesafe way\n  from event to state\n* **[Parallel states](https://kstatemachine.github.io/kstatemachine/pages/states.html#parallel-states)** - avoid a\n  combinatorial\n  explosion of\n  states\n* **[Undo transitions](https://kstatemachine.github.io/kstatemachine/pages/transitions/transitions.html#undo-transitions)** - navigate back to previous\nstate (like stack based FSMs do)\n\n* **[Optional argument](https://kstatemachine.github.io/kstatemachine/pages/events.html#event-argument)** passing for\n  events and\n  transitions\n* **[Export](https://kstatemachine.github.io/kstatemachine/pages/export.html)** state machine structure\n  to [PlantUML](https://plantuml.com/) and [Mermaid](https://mermaid.js.org/) diagrams\n* **[Persist (serialize)](https://kstatemachine.github.io/kstatemachine/pages/persistence.html)** state machine's\n  active\n  configuration and restore it later. Built-in `kotlinx.serialization` support.\n* **[Testable](https://kstatemachine.github.io/kstatemachine/pages/testing.html)** - run state machine from specified\n  state and enable internal logging\n* **[Well tested](https://github.com/kstatemachine/kstatemachine/tree/master/tests/src/commonTest/kotlin/ru/nsk/kstatemachine)** - all features are covered\nby tests\n\n## 📄 Documentation\n\n\u003e [!IMPORTANT]\n\u003e * See full documentation on [website](https://kstatemachine.github.io/kstatemachine)\n\u003e * [KDoc for classes](https://kstatemachine.github.io/kstatemachine/kdoc/index.html)\n\n## ❤️ Sponsors\n\nI highly appreciate that you donate or become a sponsor to support the project.\nIf you find this project useful you can support it by:\n\n* Pushing the ⭐ star-button\n* Using ❤️github-sponsors button to see supported donation methods\n\n## 🚀 Quick start sample\n\n### 🚦Finishing traffic light\n\n```mermaid\nstateDiagram-v2\n    direction TB\n\n    classDef red fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:black\n    classDef yellow fill:yellow,color:black,font-weight:bold,stroke-width:2px,stroke:black\n    classDef green fill:green,color:white,font-weight:bold,stroke-width:2px,stroke:black\n\n    [*] --\u003e RedState\n    RedState --\u003e YellowState: SwitchEvent\n    YellowState --\u003e GreenState: SwitchEvent\n    GreenState --\u003e [*]\n\n    class RedState red\n    class YellowState yellow\n    class GreenState green\n```\n\n```kotlin\n// define your Events\nobject SwitchEvent : Event\n\n// define your States as classes or objects\nsealed class States : DefaultState() {\n    object RedState : States()\n    object YellowState : States()\n\n    // machine finishes when enters [FinalState]\n    object GreenState : States(), FinalState\n}\n\nfun main() = runBlocking {\n    // create state machine and configure its structure in a setup block\n    val machine = createStateMachine(scope = this) {\n        addInitialState(RedState) {\n            // add state listeners\n            onEntry {\n                println(\"Enter red\")\n                // you can call suspendable code if necessary\n                delay(10)\n            }\n            onExit { println(\"Exit red\") }\n\n            // setup transition\n            transition\u003cSwitchEvent\u003e {\n                targetState = YellowState\n                // add transition listener\n                onTriggered { println(\"Transition triggered\") }\n            }\n        }\n\n        addState(YellowState) {\n            transition\u003cSwitchEvent\u003e(targetState = GreenState)\n        }\n\n        addFinalState(GreenState)\n\n        onFinished { println(\"Finished\") }\n    }\n    // you can observe state machine changes using [Flow] along with simple listeners\n    val statesFlow = machine.activeStatesFlow()\n\n    // you can process events after state machine has been started even from listener callbacks\n    machine.processEvent(SwitchEvent) // machine goes to [YellowState]\n    machine.processEvent(SwitchEvent) // machine goes to [GreenState]\n}\n```\n\n## ✍️ Publications\n\n* [Integrating State Machines with MVI Architecture in Kotlin for Reactive Android Apps](https://medium.com/p/7327c3ff34f3)\n\n## 🧪 Samples\n\n* [Android 2D shooter game sample](https://github.com/kstatemachine/android-kstatemachine-sample)\n\n  The library itself does not depend on Android.\n\n  \u003cp align=\"center\"\u003e\n      \u003cimg src=\"https://github.com/kstatemachine/android-kstatemachine-sample/blob/main/images/android-app-sample.gif\"\n          alt=\"Android sample app\" width=\"30%\" height=\"30%\"/\u003e\n  \u003c/p\u003e\n* [Compose 2D shooter game sample](https://github.com/KStateMachine/compose-kstatemachine-sample)\n* [Finished state sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedStateSample.kt)\n* [Transition on FinishedEvent sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventSample.kt)\n* [FinishedEvent using with DataState sample](./samples/src/commonMain/kotlin/ru/nsk/samples/FinishedEventDataStateSample.kt)\n* [Undo transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/UndoTransitionSample.kt)\n* [PlantUML nested states export sample](./samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportSample.kt)\n* [Mermaid nested states export sample](./samples/src/commonMain/kotlin/ru/nsk/samples/MermaidExportSample.kt)\n* [PlantUML with UmlMetaInfo export sample](./samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlExportWithUmlMetaInfoSample.kt)\n* [PlantUML with ExportMetaInfo unsafe export sample](https://github.com/KStateMachine/kstatemachine/tree/master/samples/src/commonMain/kotlin/ru/nsk/samples/PlantUmlUnsafeExportWithExportMetaInfoSample.kt)\n* [Inherit transitions by grouping states sample](./samples/src/commonMain/kotlin/ru/nsk/samples/InheritTransitionsSample.kt)\n* [Minimal sealed classes sample](./samples/src/commonMain/kotlin/ru/nsk/samples/MinimalSealedClassesSample.kt)\n* [Usage without Kotlin Coroutines sample](./samples/src/commonMain/kotlin/ru/nsk/samples/StdLibMinimalSealedClassesSample.kt)\n* [Minimal syntax sample](./samples/src/commonMain/kotlin/ru/nsk/samples/MinimalSyntaxSample.kt)\n* [Guarded transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/GuardedTransitionSample.kt)\n* [Cross-level transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/CrossLevelTransitionSample.kt)\n* [Typesafe transition sample](./samples/src/commonMain/kotlin/ru/nsk/samples/TypesafeTransitionSample.kt)\n* [Event recording sample](./samples/src/commonMain/kotlin/ru/nsk/samples/SerializationEventRecordingSample.kt)\n* [Complex syntax sample](./samples/src/commonMain/kotlin/ru/nsk/samples/ComplexSyntaxSample.kt)\n  shows many syntax variants and library possibilities, so it looks messy\n\n## 💾 Install\n\nKStateMachine is available on `Maven Central` and `JitPack` repositories.\n\nSee [install section in the docs](https://kstatemachine.github.io/kstatemachine/pages/install.html) for details.\n\n### Maven Central\n\n```kotlin\ndependencies {\n    // multiplatform artifacts, where \u003cTag\u003e is a library version.\n    implementation(\"io.github.nsk90:kstatemachine:\u003cTag\u003e\")\n    implementation(\"io.github.nsk90:kstatemachine-coroutines:\u003cTag\u003e\")\n    implementation(\"io.github.nsk90:kstatemachine-serialization:\u003cTag\u003e\")\n}\n```\n\n## 🏗️ Build\n\nRun `./gradlew build` or build with `Intellij IDEA`.\n\n## 🤝 Contribution\n\nThe library is in development phase. You are welcome to propose useful features and contribute to the project.\nSee [CONTRIBUTING](./CONTRIBUTING.md) file.\n\n## 🙋 Support\n\nI am open to answer you questions and feature requests. Fill free to use any of communication channels to\ngive your feedback.\n\n* [Slack channel](https://kotlinlang.slack.com/archives/C07DVAEKLM8) or\n  [GitHub discussions](https://github.com/kstatemachine/kstatemachine/discussions) - best for questions and discussions\n* [GitHub issues](https://github.com/KStateMachine/kstatemachine/issues) - best for bugs and feature requests\n\nIf you use some other platforms to ask questions or mention the library, I recommend adding a \u003cins\u003elink\u003c/ins\u003e to this\nGitHub project or using `#kstatemachine` tag.\n\n## 🗺️ Roadmap\n\n* Create `Intellij IDEA Plugin` for state machine visualization and edition\n\n## 🏅 Thanks to supporters\n\n[![Stargazers repo roster for @kstatemachine/kstatemachine](https://reporoster.com/stars/dark/kstatemachine/kstatemachine)](https://github.com/kstatemachine/kstatemachine/stargazers)\n[![Forkers repo roster for @kstatemachine/kstatemachine](https://reporoster.com/forks/dark/kstatemachine/kstatemachine)](https://github.com/kstatemachine/kstatemachine/network/members)\n\n## 🖋️ License\n\nLicensed under permissive [Boost Software License](./LICENSE)","funding_links":["https://opencollective.com/kstatemachine","https://ko-fi.com/nskfedotov","https://yoomoney.ru/to/4100118569686448"],"categories":["Libraries","\u003ca name=\"Kotlin\"\u003e\u003c/a\u003eKotlin"],"sub_categories":["Architecture","Kotlin"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKStateMachine%2Fkstatemachine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKStateMachine%2Fkstatemachine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKStateMachine%2Fkstatemachine/lists"}