[rinekri]

What

ru.kode.way.dsl.Graph declares a navigation graph in Kotlin, as an alternative to .dot files and the Gradle plugin. A Graph gives the runtime a Schema and a NodeBuilder, just as generated code does. That means NavigationService, extension points and way-compose work the same with either one, and DSL and generated schemas can include each other.

It ships as a separate artifact, ru.kode:way-dsl (module :way-dsl, package ru.kode.way.dsl), with the same targets as :way: JVM, Android and iOS. It depends on ru.kode:way via api, so one dependency is enough:

implementation("ru.kode:way-dsl:<version>")

Nothing in :way had to become public for it; it uses only the existing public API.

Usage

object LoginGraph : Graph("Login") {
  val login = parameterizedFlow<String, Int>("login") // built with a String, Finish(result: Int)
  val credentials = screen("credentials")
  val otp = parameterizedScreen<String>("otp")
  init { login to credentials to otp }
}

object AppGraph : Graph("App") {
  val app = flow<Unit>("app")
  val intro = screen("intro")
  val login = include("login", LoginGraph.login) // `type = schema`, typed by the included root
  val lastStep = deepHistory("lastStep")
  init {
    app to intro
    app to login
    app to lastStep
  }
}

NavigationService<Unit>(
  AppGraph.nodeBuilder {
    flow(AppGraph.app) { AppFlowNode() }
    screen(AppGraph.intro) { IntroScreen() }
    include(AppGraph.login) { userName: String -> LoginGraph.nodeBuilder { /* ... */ } }
  },
  onFinishRequest = { Finish(Unit) },
)

Supported:

• Typed parameters and results.
  • Declarations: flow<R>, parameterizedFlow<P, R>, parallel<R>, parameterizedParallel<P, R>, parameterizedScreen<P>.
  • include(id, OtherGraph.root) takes the payload and result types of the included root.
  • Targets and factories are typed, so no Any? reaches user code.
  • A nullable P works as in codegen (NullPayload; a nullable root starts with null).
• Child flow results: event.childFlowResult(AppGraph.login).
• History nodes: history(id) and deepHistory(id), with the same placement rules as Parser.kt. Their target is the runtime HistoryTarget, and they need no factory.
• Nested parallel flows: a parallel can be the root or sit under a flow, a screen or another parallel. Regions can be local flows, parallel flows or included graphs.
• Fan-in: an included graph can have several parents, as long as none is a parallel and all are in the same region. Schema.targets returns every path, and target(payload, via = parent) is the counterpart of the generated <id>Via<Parent>.
• Validation on first use mirrors Parser.kt:
  • one root, no cycles, children under the root flow and under every parallel;
  • several parents only for an include, and no children under an include;
  • history nodes placed correctly, and a factory for every non-history node.

Not supported, compared with .dot:

• screens as direct regions of a parallel (wrap them in a flow);
• full targets with ancestor payloads (use AbsoluteTarget);
• typed region accessors (use Schema.regionByName);
• a separate node builder per local flow (include a graph instead).

A DSL target under a parallel starts at its closest flow, not at the flow above the parallel; both resolve to the same node.

The README has a new "Kotlin DSL" section, and the CHANGELOG has an Unreleased entry. :way-dsl:jvmTest is added to the CI task list, and :way-dsl to the release workflow's test and publish steps. No version bump.

Testing

• GraphTest (13 tests) covers:
  • validation errors and relative targets;
  • typed and nullable payloads, MissingPayloadException and missing factories;
  • child flow results, history placement, nested parallels and fan-in.
• DslParityTest (6 tests) runs the same event sequences on generated graphs (dsl-parity-*.dot in way-dsl/src/commonTest/way) and on equivalent DSL graphs. The active path, alive paths and node payloads must be identical after every step. It covers:
  • a parameterized screen and a local child flow;
  • an included graph with payloads and results;
  • a parallel root;
  • typed params with a null and a non-null root payload;
  • shallow and deep history;
  • nested parallels;
  • fan-in.
• Test helpers from :way (TestNodeBuilder, TestFlowNode, ...) are copied into way-dsl/src/commonTest, because KMP has no test fixtures.
• These pass locally:
  • ./gradlew spotlessCheck;
  • the CI task list;
  • ./gradlew build, excluding the six iosSimulatorArm64Test / iosX64Test tasks, since no simulator runtime is installed on the machine used.
• The iOS test binaries compile and link.

Codegen bugs found on master (not fixed here)

• Generated builder for a nested local flow cannot build its children (root segment duplicated) #19: the generated builder of a local flow inside a plain flow duplicates the root segment. The parity tests build that flow by hand on the generated side.
• Codegen: history node under a parallelFlow is generated as a region and crashes the builder #20: a history node under a parallelFlow is generated as a region and the builder crashes on entering the parallel. The parity fixture leaves it out on the .dot side. The DSL excludes history nodes from regions, and a DSL-only check covers a deep history of a parallel restoring nested regions.