Skip to content

Write Datastar safely in Kotlin.

A Datastar toolchain for Kotlin. An SDK for Ktor and Spring, assertions for your tests, an analysis for your CI, and two editor extensions.

The elders of Bonereach asked Gorvek what a warrior wants of a stream.

"That it flows when I say flow. That it stops when I say stop. That it carries my will to the far shore, and nothing else."

"And the JavaScript?"

"I do not know the word."

Gorvek of Bonereach, who walked out of the Ashfall with iron in his hand

Datastar lives in strings your compiler never reads.

Each of these compiles, and without Streamlord you find out in the browser. Streamlord stops all four: the first two in your editor and in CI, the last two in the SDK itself.

Kotlin takes the dollar

val heads = 13
button { dataOnClick("$heads++") }

Kotlin puts 13 where $heads stood. The browser gets 13++, and the button does nothing.

Caught by: Your editor, and CIMore

A modifier with a dot

<form data-on:submit.prevent="@post('/heads')">

Datastar waits for an event named submit.prevent, which never comes. The form posts the old way and the page reloads.

Caught by: Your editor, and CIMore

A patch with nowhere to go

patchElements(
    "<li>A new head</li>",
    mode = ElementPatchMode.APPEND,
)

Append needs a selector, and the browser rejects the event without one. Streamlord throws where you build it instead.

Caught by: The SDK, before a byte is sentMore

An event that never leaves

writeStringUtf8("event: datastar-patch-signals\n")
writeStringUtf8("data: signals {\"heads\":14}\n\n")
// and no flush()

Written by hand without a flush, the event waits in a buffer, on an open stream for minutes. Streamlord flushes every event.

Caught by: The SDK, on every eventMore

The tabs below follow the first one, dataOnClick("$heads++"), through all four tools.

Four tools, designed together.

One feed, from start to finish: built, tested, broken by accident, and caught. Adopt one tool, or all four.

Build the feed. The handler reads the count from the page and sends back one more.

get("/feed") {
    val heads = call.readSignals().int("heads") ?: 0
    call.respondDatastar {
        patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
            li { +"A new head hangs on the wall" }
        }
        patchSignals("heads" to heads + 1)
    }
}

$heads

    On the wire

    Press Run. The frames the server sends come back here, encoded by the same encoder the golden-file tests check.

    Asserted the same way in your tests:

    events.assertPatchElements(selector = "#feed", mode = ElementPatchMode.APPEND, containing = "A new head")
    events.assertSignal("heads", 14)

    Try it on the repo you have open right now.

    One dependency and one test, and every Datastar string under src/main/kotlin is read before it ships. More on the analysis

    testImplementation("io.github.markusaugust.streamlord:streamlord-analysis:0.23.0")
    private val analyzer = Analyzer()
    
    @Test
    fun `no source file interpolates a signal into Datastar`() {
        val offenders =
            java.io.File("src/main/kotlin")
                .walkTopDown()
                .filter { it.extension == "kt" }
                .flatMap { file ->
                    val source = file.readText()
                    analyzer
                        .analyzeKotlin(source)
                        .filter { it.severity == Severity.ERROR }
                        .map { it.format(file.path, source) }
                }.toList()
    
        assertTrue(offenders.isEmpty(), offenders.joinToString("\n"))
    }