Datastar Gerbil SDK

This package provides a Gerbil SDK for Datastar v1.0.2 on Gerbil v19's embedded :std/net/http/server.

(import :gerbil-datastar/http)

Streaming elements

patch-elements, patch-signals and execute-script follow the Datastar SDK specification. call-with-patch-elements takes the same options as patch-elements, but instead of a string it calls a procedure with a BufferedWriter for the elements, so HTML kept as UTF-8 bytes is written to the stream without being joined first:

(call-with-patch-elements session
  (lambda (out)
    (BufferedWriter-write out open-tag)          ; u8vectors, written as they are
    (for-each (lambda (row) (BufferedWriter-write out row)) cached-rows)
    (BufferedWriter-write out close-tag))
  selector: "#rows" mode: 'inner)

The event's bytes are those of patch-elements given the same HTML as one string: each newline starts a new data: elements line. The writer is valid only inside the procedure. A CR or NUL byte, writing nothing, or an error raised by the procedure fails the session: the event has begun, so nothing more is sent on it.

Installation

gerbil pkg install git.cons.io/jay/gerbil-datastar

Development

Install the SSE dependency, then build and test:

gerbil pkg install git.cons.io/jay/gerbil-sse
gerbil build
gerbil test -v 0 ./...

The opt-in official conformance suite requires Go:

gerbil test -v 0 -D datastar-conformance ./http/conformance-test.ss

Long-lived SSE handlers should use a server configured with response-timeout: !NoTimeout. For now, applications should send periodic events or heartbeats because disconnects are discovered by a later write or server shutdown (TODO: fix).

Example

After building the package:

gerbil env gxi ./example.ss

Open http://127.0.0.1:8001/.

License

MIT