sdk/

Architecture Decision Record: Datastar SDK

Summary

Datastar SDK provides unified tooling for building Hypermedia On Whatever you Like (HOWL) based UIs across multiple languages. While Datastar supports various plugins, the default bundle focuses on a robust Server-Sent Event (SSE) approach, addressing the lack of good SSE tooling in most languages and backends.

Decision

Provide a language-agnostic SDK with these principles:

1. Minimal Core: Keep the SDK as minimal as possible
2. Sugar Extensions: Allow per-language/framework extended features in SDK "sugar" versions

Naming Rationale

Why "Patch" instead of "Merge": The prefix "Patch" was chosen to better reflect the non-idempotent nature of these operations. Unlike PUT requests that replace entire resources, PATCH requests apply partial modifications. This aligns with our SDKs behavior where operations modify specific parts of the DOM or signal state rather than replacing them entirely.

Why "Elements" instead of "Fragments": We use "Elements" because it accurately describes what the SDK handles - complete HTML elements, not arbitrary DOM nodes like text nodes or document fragments. This naming matches the actual intent and constraints of the system, making the API clearer and more predictable for developers.

Details

Core Mechanics

The core mechanics of Datastar’s SSE support is

1. Server → Browser: Data is sent as SSE events
2. Browser → Server: Data arrives as JSON under the datastar namespace

SDK Specification

[!WARNING] All naming conventions use Go as the reference implementation. Adapt to language-specific conventions while maintaining consistency.

ServerSentEventGenerator

Required: A ServerSentEventGenerator namespace/class/struct (implementation may vary by language).

Construction / Initialization

Requirements:

ServerSentEventGenerator.send

ServerSentEventGenerator.send(
    eventType: EventType,
    dataLines: string[],
    options?: {
        eventId?: string,
        retryDuration?: durationInMilliseconds
    }
)

A unified sending function should be used internally (private/protected).

Parameters

String enum of supported events:

Implementation Requirements

Must write to response buffer in this exact order:

1. event: EVENT_TYPE\n
2. id: EVENT_ID\n (if eventId provided)
3. retry: RETRY_DURATION\n (unless default of 1000)
4. data: DATA\n (for each of the dataLines)
5. \n (end of event)
6. Should flush immediately (note: compression middleware may interfere)

Error Handling: Must return/throw errors per language conventions.

ServerSentEventGenerator.PatchElements

ServerSentEventGenerator.PatchElements(
  elements: string,
  options?: {
    selector?: string,
    mode?: ElementPatchMode,
    useViewTransition?: boolean,
    eventId?: string,
    retryDuration?: durationInMilliseconds
  }
)

Example Output

event: datastar-patch-elements
data: elements <div id="feed"><span>1</span></div>

event: datastar-patch-elements
id: 123
retry: 2000
data: mode inner
data: selector #feed
data: useViewTransition true
data: elements <div id="feed">
data: elements     <span>1</span>
data: elements </div>

event: datastar-patch-elements
data: elements <div id="id1">New content.</div>
data: elements <div id="id2">Other new content.</div>

event: datastar-patch-elements
data: mode append
data: selector #mycontainer
data: elements <div>New content</div>

event: datastar-patch-elements
data: mode remove
data: selector #feed, #otherid

event: datastar-patch-elements
data: mode remove
data: elements <div id="first"></div><div id="second"></div>

PatchElements sends HTML elements to the browser for DOM manipulation.

[!TIP]

• To remove elements, use the remove patch mode
• To execute JavaScript, send a <script> element – it will auto-execute when added to the DOM

Elements vs Fragments: Key Distinction

[!IMPORTANT] Datastar requires complete HTML elements, not fragments.

Parameters

• elements: One or more complete HTML elements. If a selector has not been specified, each top-level element must contain an ID. With ElementPatchMode remove, this parameter may be omitted when a selector is supplied.

ElementPatchMode

String enum defining how elements are patched into the DOM.

Options

Implementation

Must call ServerSentEventGenerator.send with event type datastar-patch-elements.

Data format (only include non-defaults):

• selector SELECTOR\n (if provided)
• mode PATCH_MODE\n (if not outer)
• useViewTransition true\n (if true)
• elements HTML_LINE\n (for each line of HTML)

ServerSentEventGenerator.PatchSignals

ServerSentEventGenerator.PatchSignals(
  signals: string,
  options ?: {
    onlyIfMissing?: boolean,
    eventId?: string,
    retryDuration?: durationInMilliseconds
  }
)

Example Output

event: datastar-patch-signals
data: signals {"output":"Patched Output Test","show":true,"input":"Test","user":{"name":"","email":""}}

event: datastar-patch-signals
id: 123
retry: 2000
data: onlyIfMissing true
data: signals {"output":"Patched Output Test","show":true,"input":"Test","user":{"name":"","email":""}}

PatchSignals sends signals to the browser using RFC 7386 JSON Merge Patch semantics.

Parameters

• signals: A valid JSON string containing the patch data

RFC 7386 JSON Merge Patch Behavior

Examples

// Add signal
{"newSignal": "value"}

// Update signal
{"existingSignal": "newValue"}

// Remove signal
{"signalToRemove": null}

// Complex nested patch
{
  "user": {
    "name": "Johnny",
    "email": null,
    "preferences": {
      "theme": "dark"
    }
  }
}

Options

Implementation

Must call ServerSentEventGenerator.send with event type datastar-patch-signals.

Data format:

• onlyIfMissing true\n (only if true)
• signals JSON_LINE\n (for each line of JSON)

ServerSentEventGenerator.ExecuteScript

ServerSentEventGenerator.ExecuteScript(
  script: string,
  options?: {
    autoRemove?: boolean,
    attributes?: []string,
    eventId?: string,
    retryDuration?: durationInMilliseconds
  }
)

Example Output

event: datastar-patch-elements
data: mode append
data: selector body
data: elements <script>console.log('Here')</script>

event: datastar-patch-elements
id: 123
retry: 2000
data: mode append
data: selector body
data: elements <script type="application/javascript" data-effect="el.remove()">console.log('Here')</script>

Parameters

• script: One or more lines of JavaScript.

Options

Implementation

Must call ServerSentEventGenerator.send with event type datastar-patch-elements, sending a script tag containing the JavaScript to execute. If autoRemove is true, data-effect="el.remove()" must be added to the script tag. If attributes exist, they must be added to the script tag.

Data format (only include non-defaults):

• selector body\n
• mode append\n
• elements SCRIPT_TAG\n

ReadSignals

ReadSignals parses incoming signal data from the browser into backend objects.

ReadSignals(request *http.Request, signals any) error

Parameters

Implementation

The function must parse the incoming HTTP request based on the method:

Error Handling: Must return error for invalid JSON.