Datastar Racket SDK

8.17

Datastar Racket SDK🔗ℹ

This package provides a Racket SDK for working with Datastar.

1 Usage🔗ℹ

Example usage (adapted from the Datastar Go SDK docs)

#lang racket

(require web-server/dispatch
         web-server/servlet-dispatch
         web-server/http
         datastar
         json)

(struct store (message count) #:transparent)

(define (handler req)
  ; Read signals from the request
  (define signals-data (read-signals req))
  (define current-store
    (store (hash-ref signals-data 'message "")
           (hash-ref signals-data 'count 0)))

  ; Create a Server-Sent Event response
  (datastar-response
    (list
      ; Patch elements in the DOM
      (patch-elements "<div id=\"output\">Hello from Datastar!</div>")

      ; Remove elements from the DOM
      (remove-elements "#temporary-element")

      ; Patch signals (update client-side state)
      (patch-signals (hash 'message "Updated message"
                            'count (+ (store-count current-store) 1)))

      ; Execute JavaScript in the browser
      (execute-script "console.log(\"Hello from server!\")")

      ; Redirect the browser
      (redirect "/new-page"))))

For more advanced usage with streaming updates, you can use generators:

(define (streaming-handler req)
  (datastar-response
    (in-generator
      (let loop ([i 0])
        (when (< i 10)
          (yield (patch-signals (hash 'counter i)))
          (yield (patch-elements
                   (format "<div id=\"counter\">Count: ~a</div>" i)))
          (sleep 1)
          (loop (+ i 1)))))))

For more examples, see the examples directory on GitHub.

2 Methods🔗ℹ

procedure
(datastar-response events) → response?
events : (or/c string? (sequence/c string?))

Creates an HTTP response with proper SSE headers for streaming Datastar events to the browser.

procedure
(patch-elements elements
[ #:selector selector
#:mode mode
#:use-view-transitions use-view-transitions
#:event-id event-id
#:retry-duration retry-duration])
→ string?
  elements : (or/c string? #f)
  selector : (or/c string? #f) = #f
  mode : (or/c string? #f) = #f
  use-view-transitions : (or/c boolean? #f) = #f
  event-id : (or/c string? #f) = #f
  retry-duration : (or/c exact-positive-integer? #f) = #f

Patches HTML elements into the DOM. Supports various patch modes including outer, inner, replace, prepend, append, before, after, and remove.

procedure
(remove-elements selector
[ #:event-id event-id
#:retry-duration retry-duration]) → string?
  selector : string?
  event-id : (or/c string? #f) = #f
  retry-duration : (or/c exact-positive-integer? #f) = #f

Removes elements from the DOM by CSS selector. This is a convenience function that calls patch-elements with mode ’remove’.

procedure
(read-signals request) → jsexpr?
request : request?

Parses incoming signal data from the browser. For GET requests, extracts data from the ’datastar’ query parameter. For other methods, parses the request body as JSON.

procedure
(patch-signals signals
[ #:event-id event-id
#:only-if-missing only-if-missing
#:retry-duration retry-duration]) → string?
  signals : (or/c string? jsexpr?)
  event-id : (or/c string? #f) = #f
  only-if-missing : (or/c boolean? #f) = #f
  retry-duration : (or/c exact-positive-integer? #f) = #f

Patches signals into the signal store using RFC 7386 JSON Merge Patch semantics. Supports add/update operations, removal by setting to null, and nested recursive patching.

procedure
(execute-script script
[ #:auto-remove auto-remove
#:attributes attributes
#:event-id event-id
#:retry-duration retry-duration]) → string?
  script : string?
  auto-remove : boolean? = #t
   attributes : (or/c (hash/c symbol? any/c) (listof string?) #f)
= #f
  event-id : (or/c string? #f) = #f
  retry-duration : (or/c exact-positive-integer? #f) = #f

Executes JavaScript in the browser by injecting a script tag. The script is automatically removed after execution unless auto-remove is #f.

procedure
(redirect location) → string?
location : string?

Redirects the browser to a new location using window.location. This is a convenience function that calls execute-script.

3 Constants🔗ℹ

3.1 Element Patch Modes🔗ℹ

An element patch mode is the mode in which an element is patched into the DOM.

value
ELEMENT-PATCH-MODE-OUTER : string? = "outer"

Morphs the element into the existing element.

value
ELEMENT-PATCH-MODE-INNER : string? = "inner"

Replaces the inner HTML of the existing element.

value
ELEMENT-PATCH-MODE-REMOVE : string? = "remove"

Removes the existing element.

value
ELEMENT-PATCH-MODE-REPLACE : string? = "replace"

Replaces the existing element with the new element.

value
ELEMENT-PATCH-MODE-PREPEND : string? = "prepend"

Prepends the element inside to the existing element.

value
ELEMENT-PATCH-MODE-APPEND : string? = "append"

Appends the element inside the existing element.

value
ELEMENT-PATCH-MODE-BEFORE : string? = "before"

Inserts the element before the existing element.

value
ELEMENT-PATCH-MODE-AFTER : string? = "after"

Inserts the element after the existing element.

3.2 Event Types🔗ℹ

value
EVENT-TYPE-PATCH-ELEMENTS : string? = "datastar-patch-elements"

An event for patching HTML elements into the DOM.

value
EVENT-TYPE-PATCH-SIGNALS : string? = "datastar-patch-signals"

An event for patching signals.