Installation설치

Maven Central is the only repository required. Afsm is distributed under Apache-2.0. 별도 저장소는 필요하지 않습니다. Afsm은 Apache-2.0으로 배포됩니다.

1. Verify Maven Central repositoryMaven Central 저장소 확인

   Ensure mavenCentral() is present in plugin and dependency repositories.프로젝트의 plugin 및 dependency repository에 mavenCentral()이 포함되어 있는지 확인합니다.

   settings.gradle.ktsCopy복사

   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   }
   
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
       }
   }

2. Add the modules모듈 추가

   Start with core, runtime, ViewModel integration, and the test helpers.core, runtime, ViewModel 연동, 테스트 helper부터 추가합니다.

   build.gradle.ktsCopy복사

   val afsmVersion = "0.1.0"
   
   dependencies {
       implementation("io.github.afsm:afsm-core:$afsmVersion")
       implementation("io.github.afsm:afsm-runtime:$afsmVersion")
       implementation("io.github.afsm:afsm-viewmodel:$afsmVersion")
       testImplementation("io.github.afsm:afsm-test:$afsmVersion")
   }

5-minute quickstart5분 Quickstart

This Draft flow is the smallest useful example: edit a title, start repository work, and finish in a durable Saved phase. 이 Draft 흐름은 가장 작은 실용 예제입니다. 제목을 편집하고 repository 작업을 시작한 뒤 지속되는 Saved phase로 완료합니다.

1. Define the flow types1. 흐름 타입 정의

sealed interface DraftPhase {
    data object Editing : DraftPhase
    data object Saving : DraftPhase
    data object Saved : DraftPhase
}

data class DraftData(
    val title: String = "",
    val errorMessage: String? = null,
)

typealias DraftState = AfsmState<DraftPhase, DraftData>

sealed interface DraftEvent {
    data class TitleChanged(val value: String) : DraftEvent
    data object SaveClicked : DraftEvent
    data object DraftSaveCompleted : DraftEvent
    data class DraftSaveFailed(val message: String) : DraftEvent
}

sealed interface DraftCommand {
    data class SaveDraft(val title: String) : DraftCommand
}

2. Write the executable machine2. 실행 가능한 머신 작성

val draftMachine: AfsmDefaultMachine<
    DraftState,
    DraftEvent,
    DraftCommand,
> = afsmMachine {
    initial(DraftPhase.Editing, DraftData())

    phase(DraftPhase.Editing) {
        on<DraftEvent.TitleChanged> {
            updateData { data, event ->
                data.copy(title = event.value, errorMessage = null)
            }
        }

        on<DraftEvent.SaveClicked> {
            case("valid title", condition = { data.title.isNotBlank() }) {
                transitionTo(DraftPhase.Saving)
            }
            case("missing title", condition = { data.title.isBlank() }) {
                updateData { copy(errorMessage = "Title is required.") }
            }
        }
    }

    phase(DraftPhase.Saving) {
        onEnter {
            command("SaveDraft") { DraftCommand.SaveDraft(data.title) }
        }
        on<DraftEvent.DraftSaveCompleted> {
            transitionTo(DraftPhase.Saved)
        }
        on<DraftEvent.DraftSaveFailed> {
            updateData { data, event ->
                data.copy(errorMessage = event.message)
            }
            transitionTo(DraftPhase.Editing)
        }
    }

    phase(DraftPhase.Saved)
}

Continue with the complete Draft tutorial →전체 Draft 튜토리얼 계속 읽기 →

Core concepts핵심 개념

Afsm keeps the public flow vocabulary deliberately small. Afsm은 공개 흐름 어휘를 의도적으로 작게 유지합니다.

State

Current Phase plus durable business Data. This is the output rendered by UI.현재 Phase와 지속되는 비즈니스 Data. UI가 렌더링하는 출력입니다.

Event

User intent or an external-work result entering the machine.사용자 의도 또는 외부 작업 결과가 머신으로 들어오는 입력입니다.

Command

Typed host-work request emitted by an accepted transition.허용된 전이가 내보내는 타입 안전한 host 작업 요청입니다.

Decision meaningsDecision 의미

Android integrationAndroid 연동

Afsm does not replace ViewModel. The machine owns flow rules; ViewModel owns Android lifecycle and external work. Afsm은 ViewModel을 대체하지 않습니다. 머신은 흐름 규칙을, ViewModel은 Android lifecycle과 외부 작업을 맡습니다.

class DraftViewModel(
    private val repository: DraftRepository,
) : ViewModel() {
    private val host = afsmHost(
        machine = draftMachine,
        commandHandler = { command: DraftCommand, send ->
            when (command) {
                is DraftCommand.SaveDraft -> repository.save(command.title).fold(
                    onSuccess = { send(DraftEvent.DraftSaveCompleted) },
                    onFailure = { error ->
                        send(DraftEvent.DraftSaveFailed(error.message.orEmpty()))
                    },
                )
            }
        },
    )

    val state: StateFlow<DraftState> = host.state

    fun updateTitle(value: String) = host.send(DraftEvent.TitleChanged(value))
    fun save() = host.send(DraftEvent.SaveClicked)
}

API quick referenceAPI 빠른 참조

The table below covers the main public surface. Use the full API page for signatures and overloads. 아래 표는 주요 공개 surface를 다룹니다. signature와 overload는 전체 API 문서를 확인하세요.

DSL operationsDSL 연산

Open the full public API reference →전체 공개 API 레퍼런스 열기 →

Guides가이드

Example path예제 학습 순서

Start small, then add Android and runtime complexity only when the previous flow is clear.작게 시작하고 이전 흐름이 명확해진 뒤에만 Android와 runtime 복잡성을 추가합니다.

1. DraftMinimal machine and ViewModel host최소 machine과 ViewModel hostTry example예제 실행
2. AuthValidation and durable completion검증과 지속되는 완료 상태Try example예제 실행
3. CheckoutDynamic input, retry, stale results, restoration동적 입력, 재시도, 오래된 결과, 복원Try example예제 실행
4. ProductEditorAfter Checkout: long flow and phase-owned cancellationCheckout 이후: 긴 흐름과 phase 소유 취소Try example예제 실행

{}

Why Afsm existsAfsm을 만든 이유

Complex Android screens can reach a point where each handler looks reasonable but the complete flow exists across ViewModel updates, coroutines, callbacks, repositories, and tests. Afsm makes those phase-dependent rules local and executable without replacing ViewModel or imposing an app-wide MVI framework. 복잡한 Android 화면은 각 handler가 합리적으로 보여도 전체 흐름이 ViewModel 업데이트, 코루틴, 콜백, repository, 테스트에 흩어질 수 있습니다. Afsm은 ViewModel을 대체하거나 앱 전체 MVI를 강제하지 않고 단계별 규칙을 한곳에서 실행 가능하게 만듭니다.