Datastar SDK for Raku

E. Alvarez [email protected]

use Datastar::SDK;

class MyRequest does RequestAdapter {
    method request-method(--> Str) { ... }
    method query-parameter(Str:D $name) { ... }
    method body-text(--> Str) { ... }
    method protocol-version(--> Str) { ... }
}

class MyResponse does ResponseAdapter {
    method set-header(Str:D $name, Str:D $value) { ... }
    method write(Str:D $chunk) { ... }
    method flush() { ... }
}

my $sse = ServerSentEventGenerator.new(
    request => $request,
    response => $response,
);

my %signals = read-signals($request);

$sse.patch-elements(
    '<section id="status">Saved</section>',
);

$sse.patch-signals(%(
    pending => False,
    error => JSON-NULL,
));

This is a data-oriented Datastar SDK written in Raku. The SDK implements the Datastar SDK ADR with zero runtime dependencies. Raku++ is the primary compiler used by this project to develop, test, and build it.

Install the distribution from the zef ecosystem:

zef install 'Datastar::SDK:auth<zef:ealvar3z>'

Then install the Raku++ compiler to run it with Raku++.

The core API follows Datastar's SDK architecture decision record and the constants, defaults, literals, and enums in the v1 SDK configuration. The configuration's shape is described by its JSON Schema. Scoped view transitions use the ADR's newer viewTransitionSelector option.

The API follows this data-oriented flow:

HTTP request adapter
  -> native Raku signals
  -> event hash
  -> SSE encoding
  -> HTTP response adapter

ServerSentEventGenerator is the only stateful SDK object. It owns the response lifecycle, serializes complete event writes with a Lock, and flushes after each event. Event constructors and JSON handling operate on native Raku data.

Implement the small RequestAdapter and ResponseAdapter roles for the HTTP server used by the application. The synopsis shows the complete method contracts.

For GET and DELETE requests, query-parameter must return the URL-decoded value of the requested query parameter. read-signals asks for the configured datastar parameter and parses its JSON value. For POST, PUT, and PATCH, it parses body-text directly.

Raku-style kebab-case option names correspond to the ADR's Go-style names:

• event-id corresponds to eventId.

• retry-duration corresponds to retryDuration.

• use-view-transition corresponds to useViewTransition.

• view-transition-selector corresponds to viewTransitionSelector.

• only-if-missing corresponds to onlyIfMissing.

• auto-remove corresponds to autoRemove.

patch-signals accepts either native associative data or a JSON string. The string form preserves formatting when multiline JSON must be streamed exactly. Use the exported JSON-NULL sentinel to retain JSON merge-patch removal values inside native Raku data.

The examples guide contains Raku ports of Datastar's Go examples:

• A Hello World server that streams a complete element for every message prefix.

• A zero-dependency hot-reload server driven by a long-lived SSE request.

Run either example from the repository root:

rakupp -Ilib -Iexamples/lib examples/helloworld/main.raku
rakupp -Ilib -Iexamples/lib examples/hotreload/main.raku

Run the unit tests from the repository root:

for test in t/*.rakutest; do rakupp -Ilib "$test"; done
RAKUPP_PARALLEL=1 rakupp -Ilib t/03-generator.rakutest

Run the conformance server from the repository root:

rakupp -Ilib t/conformance-server.raku

In another terminal:

go run github.com/starfederation/datastar/sdk/tests/cmd/datastar-sdk-tests@latest \
  -server http://127.0.0.1:7331 -v

Verify that the conformance server can be transpiled to native C++:

RAKULIB=lib rakupp --cpp t/conformance-server.raku >/dev/null

An exit status of 0 means native code generation is available. Status 5 means --exe would fall back to AOT or bundling.

Compile and run the native conformance server:

sdk_tmp=$(mktemp -d)
RAKULIB=lib \
  rakupp --exe t/conformance-server.raku \
  -o "$sdk_tmp/datastar-raku-conformance"
RAKULIB=lib "$sdk_tmp/datastar-raku-conformance"

The compile step must report Compiled (native) without a fallback notice. Run the same Go conformance command against the compiled server.

The conformance server is test-only. Production integrations should adapt the roles to their HTTP stack so writes and flush errors propagate naturally.

Copyright 2026 E. Alvarez.

This software is licensed under the Artistic License 2.0.