Datastar Racket SDK
1 Usage
2 Methods
datastar-response
patch-elements
remove-elements
read-signals
patch-signals
execute-script
redirect
3 Constants
3.1 Element Patch Modes
ELEMENT-PATCH-MODE-OUTER
ELEMENT-PATCH-MODE-INNER
ELEMENT-PATCH-MODE-REMOVE
ELEMENT-PATCH-MODE-REPLACE
ELEMENT-PATCH-MODE-PREPEND
ELEMENT-PATCH-MODE-APPEND
ELEMENT-PATCH-MODE-BEFORE
ELEMENT-PATCH-MODE-AFTER
3.2 Event Types
EVENT-TYPE-PATCH-ELEMENTS
EVENT-TYPE-PATCH-SIGNALS
9.0

Datastar Racket SDK🔗ℹ

Jay Bonthius <jay@jmbmail.com>

 (require datastar) package: datastar

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 
  #:namespace namespace 
  #: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
  namespace : (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. The namespace parameter can be used to specify SVG or MathML namespaces when patching elements.

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.