Datastar Go SDK

https://github.com/starfederation/datastar-go
Admin
This package provides a Go SDK for working with Datastar, enabling developers to interact with...
Tokens:55,565
Snippets:400
Trust Score:8.5
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install Datastar Go SDK with go get

Source: https://github.com/starfederation/datastar-go/blob/main/README.md

Use this command to install the Datastar Go SDK. Requires Go 1.24 or later.

```bash
go get github.com/starfederation/datastar-go
```

--------------------------------

### Prefetch usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Example call to Prefetch with two URLs, emitting a speculation-rules script.

```go
sse.Prefetch("/dashboard", "/reports")
```

--------------------------------

### Gzip usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Example of using WithGzip with WithGzipLevel to set gzip.BestCompression.

```go
datastar.WithGzip(datastar.WithGzipLevel(gzip.BestCompression))
```

--------------------------------

### Console convenience method usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Example usage of ConsoleLogf and ConsoleError methods.

```go
sse.ConsoleLogf("User %s signed in", user.Name)
sse.ConsoleError(someErr)
```

--------------------------------

### Brotli usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Example of using WithBrotli with WithBrotliLevel to set quality 11.

```go
datastar.WithBrotli(datastar.WithBrotliLevel(11))
```

--------------------------------

### ElementPatchModeFromString example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Example usage of ElementPatchModeFromString with error handling.

```go
mode, err := datastar.ElementPatchModeFromString("append")
if err != nil {
	log.Printf("invalid mode: %v", err)
	return
}
sse.PatchElements(html, datastar.WithMode(mode))
```

--------------------------------

### Deflate usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Example of using WithDeflate with WithDeflateLevel and WithDeflateDictionary.

```go
datastar.WithDeflate(
	datastar.WithDeflateLevel(zlib.BestSpeed),
	datastar.WithDeflateDictionary([]byte("common-prefix")),
)
```

--------------------------------

### Redirect usage examples

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Example calls to Redirect and Redirectf. Redirect sends a redirect to the given URL, Redirectf formats the URL with fmt.Sprintf.

```go
sse.Redirect("/new-page")
sse.Redirectf("/report?year=%d&month=%d", 2024, 6)
```

--------------------------------

### WithCompression usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Example of using WithCompression with Gzip, Brotli, and ClientPriority strategy. This configures compression for the SSE stream.

```go
sse := datastar.NewSSE(w, r,
	datastar.WithCompression(
		datastar.WithGzip(datastar.WithGzipLevel(gzip.BestCompression)),
		datastar.WithBrotli(),
		datastar.WithClientPriority(),
	),
)
```

--------------------------------

### Basic Datastar Go SDK usage example

Source: https://github.com/starfederation/datastar-go/blob/main/README.md

Shows how to read signals from a request, create a Server-Sent Event writer, patch DOM elements, remove elements, patch signals, execute JavaScript, and redirect. The example defines a Store struct with Message and Count fields and uses datastar.ReadSignals to populate it.

```go
import (
    "net/http"
    "github.com/starfederation/datastar-go/datastar"
)

// Read signals from request
type Store struct {
    Message string `json:"message"`
    Count   int    `json:"count"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    // Read signals from the request
    store := &Store{}
    if err := datastar.ReadSignals(r, store); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Create a Server-Sent Event writer
    sse := datastar.NewSSE(w, r)

    // Patch elements in the DOM
    sse.PatchElements(`<div id="output">Hello from Datastar!</div>`)

    // Remove elements from the DOM
    sse.RemoveElement("#temporary-element")

    // Patch signals (update client-side state)
    sse.MarshalAndPatchSignals(map[string]any{
        "message": "Updated message",
        "count":   store.Count + 1,
    })

    // Execute JavaScript in the browser
    sse.ExecuteScript(`console.log("Hello from server!")`)

    // Redirect the browser
    sse.Redirect("/new-page")
}
```

--------------------------------

### ExecuteScript basic example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Basic usage of ExecuteScript to run a console.log in the browser.

```go
sse := datastar.NewSSE(w, r)
if err := sse.ExecuteScript(`console.log("Hello from server!")`); err != nil {
	log.Printf("execute failed: %v", err)
}
```

--------------------------------

### ReplaceURLQuerystring example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Shows how to replace the current URL with a new query string. The example passes a url.Values map with a page parameter set to "2".

```go
sse.ReplaceURLQuerystring(r, url.Values{"page": {"2"}})
```

--------------------------------

### Basic SSE usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

A complete Go program demonstrating how to use NewSSE to stream server-sent events. It creates an SSE generator, patches elements with a timestamp every second, and serves it on /stream.

```go
package main

import (
	"log"
	"net/http"
	"time"

	"github.com/starfederation/datastar-go/datastar"
)

func handler(w http.ResponseWriter, r *http.Request) {
	sse := datastar.NewSSE(w, r)

	for i := 0; i < 5; i++ {
		if err := sse.PatchElements(`<div id="tick">tick ` + time.Now().String() + `</div>`); err != nil {
			return
		}
		time.Sleep(time.Second)
	}
}

func main() {
	http.HandleFunc("/stream", handler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

--------------------------------

### Example usage of WithSelectorID and WithModeInner

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Shows how to use the shortcuts in a call to sse.PatchElements, targeting an element by ID and using inner mode.

```go
err := sse.PatchElements(html, datastar.WithSelectorID("menu"), datastar.WithModeInner())
```

--------------------------------

### MarshalAndPatchSignals usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/04-signals.md

Example call to MarshalAndPatchSignals with a map containing message and count fields. The count uses store.Count + 1.

```go
sse.MarshalAndPatchSignals(map[string]any{
	"message": "Updated message",
	"count":   store.Count + 1,
})
```

--------------------------------

### GetSSE usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Example of using GetSSE to generate an action attribute string for a button's data-on-click attribute. The URL is formatted with fmt.Sprintf, passing 2 as the step parameter.

```go
html := fmt.Sprintf(`<button data-on-click="%s">Go</button>`,
	datastar.GetSSE("/increment?step=%d", 2))
```

--------------------------------

### Example: PatchSignals with raw JSON

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/04-signals.md

Example of calling PatchSignals with a raw JSON payload. It creates an SSE generator from the HTTP response writer and request, then sends the signals. On error, it logs the failure.

```go
sse := datastar.NewSSE(w, r)
if err := sse.PatchSignals([]byte(`{"message":"Updated","count":3}`)); err != nil {
	log.Printf("patch signals failed: %v", err)
}
```

--------------------------------

### Basic PatchElements example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/02-elements.md

Shows a basic usage of PatchElements to send a single HTML element to the client. Logs an error if the patch fails.

```go
sse := datastar.NewSSE(w, r)
if err := sse.PatchElements(`<div id="output">Hello from Datastar!</div>`); err != nil {
	log.Printf("patch failed: %v", err)
}
```

--------------------------------

### PatchSignalsIfMissingRaw usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/04-signals.md

Example call to PatchSignalsIfMissingRaw with a JSON string. Shows error handling by returning the error.

```go
if err := sse.PatchSignalsIfMissingRaw(`{"user":"guest"}`); err != nil {
	return err
}
```

--------------------------------

### WithExecuteScriptAttributeKVs signature and usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Returns an ExecuteScriptOption that formats key-value pairs as %s="%s". Panics with "WithExecuteScriptAttributeKVs requires an even number of arguments" if the number of arguments is odd. The example shows usage with sse.ExecuteScript.

```go
func WithExecuteScriptAttributeKVs(kvs ...string) ExecuteScriptOption
```

```go
sse.ExecuteScript(`alert("hi")`, datastar.WithExecuteScriptAttributeKVs("type", "module"))
```

--------------------------------

### WithSelectorf usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/02-elements.md

Example usage of WithSelectorf with sse.PatchElements, formatting a selector like '#row-4'.

```go
sse.PatchElements(html, datastar.WithSelectorf("#%s-%d", "row", 4))
```

--------------------------------

### PatchElementTempl example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Example usage of PatchElementTempl with a Templ component. Renders the component to a byte buffer using sse.Context(), then patches. Errors are wrapped as "failed to patch element: %w".

```go
import "github.com/a-h/templ"

component := templ.ComponentFunc(func(ctx context.Context, w io.Writer) error {
	_, err := io.WriteString(w, `<div id="x">templ html</div>`)
	return err
})
sse.PatchElementTempl(component)
```

--------------------------------

### PatchElementf example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Example usage of PatchElementf to patch an element with a formatted string. Uses a name variable and returns an error if the patch fails.

```go
name := "Ada"
if err := sse.PatchElementf(`<b id="user">%s</b>`, name); err != nil {
	return err
}
```

--------------------------------

### DispatchCustomEvent example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Shows how to dispatch a custom event with a detail struct. The detail is marshaled to JSON and passed as the event's detail parameter. The example uses WithDispatchCustomEventSelector to target the event.

```go
type MyDetail struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

err := sse.DispatchCustomEvent(
	"todo:created",
	MyDetail{ID: 7, Name: "Buy milk"},
	datastar.WithDispatchCustomEventSelector("#list"),
)
if err != nil {
	return err
}
```

--------------------------------

### Example: PatchSignals with only-if-missing and retry override

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/04-signals.md

Example of calling PatchSignals with the WithOnlyIfMissing option set to true and a custom retry duration of 3 seconds. It sends a JSON payload with a theme signal. On error, it logs the failure.

```go
err := sse.PatchSignals(
	[]byte(`{"theme":"dark"}`),
	datastar.WithOnlyIfMissing(true),
	datastar.WithPatchSignalsRetryDuration(3*time.Second),
)
if err != nil {
	log.Printf("patch signals failed: %v", err)
}
```

--------------------------------

### WithZstd usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Example of using WithZstd with a custom encoder level. This appends a Zstd Compressor with encoding zstd.Encoding.

```go
datastar.WithZstd(zstd.WithEncoderLevel(zstd.SpeedBestCompression))
```

--------------------------------

### RemoveElement usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Example of using RemoveElement to remove an element by selector, logging an error if removal fails.

```go
if err := sse.RemoveElement("#temporary-element"); err != nil {
	log.Printf("remove failed: %v", err)
}
```

--------------------------------

### ExecuteScript with module script and auto-remove disabled

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Example using WithExecuteScriptAttributes and WithExecuteScriptAutoRemove options to set the script as a module and persist it.

```go
err := sse.ExecuteScript(
	`document.title = "Done";`,
	datastar.WithExecuteScriptAttributes(`type="module"`),
	datastar.WithExecuteScriptAutoRemove(false),
)
```

--------------------------------

### Low-level send with options

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Example of calling Send with event type, data lines, and options for event ID and retry duration. Logs an error if the send fails.

```go
err := sse.Send(
	datastar.EventTypePatchElements,
	[]string{`<div id="x">hi</div>`},
	datastar.WithSSEEventId("evt-42"),
	datastar.WithSSERetryDuration(2*time.Second),
)
if err != nil {
	log.Printf("send failed: %v", err)
}
```

--------------------------------

### WithContext usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Creates a derived context with a requestID value and passes it to NewSSE via WithContext.

```go
ctx := context.WithValue(r.Context(), "requestID", "abc-123")
sse := datastar.NewSSE(w, r, datastar.WithContext(ctx))
```

--------------------------------

### Error Handling in Consumer Code

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/errors.md

Example of how to catch and handle errors from ReadSignals and PatchElements in consumer code.

```APIDOC
## Error Handling in Consumer Code

### Description
Demonstrates how to handle errors returned by `ReadSignals` and `PatchElements` in consumer code.

### Code Example
```go
if err := datastar.ReadSignals(r, &store); err != nil {
	if errors.Is(err, http.ErrBodyReadAfterClose) {
		http.Error(w, "call ReadSignals before NewSSE", http.StatusInternalServerError)
		return
	}
	http.Error(w, err.Error(), http.StatusBadRequest)
	return
}

sse := datastar.NewSSE(w, r)
if err := sse.PatchElements(html); err != nil {
	// err wraps "failed to send elements: context cancelled: ..." when the
	// client disconnected. Log and bail out of the loop.
	log.Printf("stream error: %v", err)
	return
}
```
```

--------------------------------

### Context method usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Passes the stream context to a templ component render that needs request-scoped values.

```go
// Pass the stream context to a templ component render that needs request-scoped values.
if err := sse.PatchElementTempl(myTemplComponent); err != nil {
	log.Println(err)
}
```

--------------------------------

### ReadSignals usage example

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/04-signals.md

Example of using ReadSignals to unmarshal signals into a struct. It shows the Store struct, the call to ReadSignals, error handling, and a comment emphasizing that ReadSignals must be called before creating the SSE stream.

```go
type Store struct {
	Message string `json:"message"`
	Count   int    `json:"count"`
}

store := &Store{}
if err := datastar.ReadSignals(r, store); err != nil {
	http.Error(w, err.Error(), http.StatusBadRequest)
	return
}
// IMPORTANT: call ReadSignals BEFORE creating the SSE stream,
// because NewSSE does not read the body.
sse := datastar.NewSSE(w, r)
```

--------------------------------

### Long-running event loop with early exit using IsClosed

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Example loop that checks IsClosed to exit early if the connection is closed, then sends a signal patch and sleeps. Useful for long-running SSE event loops.

```go
for {
	if sse.IsClosed() {
		return
	}
	if err := sse.PatchSignals([]byte(`{"progress": "1"}`)); err != nil {
		return
	}
	time.Sleep(time.Second)
}
```

--------------------------------

### SSE action-string generator signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Signatures for the five SSE action-string generators: GetSSE, PostSSE, PutSSE, PatchSSE, and DeleteSSE. Each formats the URL with fmt.Sprintf and wraps it in the corresponding @get, @post, @put, @patch, or @delete action attribute.

```go
func GetSSE(urlFormat string, args ...any) string
func PostSSE(urlFormat string, args ...any) string
func PutSSE(urlFormat string, args ...any) string
func PatchSSE(urlFormat string, args ...any) string
func DeleteSSE(urlFormat string, args ...any) string
```

--------------------------------

### Context cancellation error

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Example showing that Send returns an error when the context is canceled. The error message is 'context cancelled: context canceled'.

```go
ctx, cancel := context.WithCancel(r.Context())
sse := datastar.NewSSE(w, r, datastar.WithContext(ctx))
cancel()

err := sse.Send(datastar.EventTypePatchElements, []string{"x"})
// err != nil; err.Error() == "context cancelled: context canceled"
```

--------------------------------

### PatchElements with selector, mode, and view transitions

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/02-elements.md

Shows how to use PatchElements with options: WithSelector, WithMode (append), WithUseViewTransitions, and WithViewTransitionSelector. Logs an error if the patch fails.

```go
err := sse.PatchElements(
	`<li id="item-3">Three</li>`,
	datastar.WithSelector("#list"),
	datastar.WithMode(datastar.ElementPatchModeAppend),
	datastar.WithUseViewTransitions(true),
	datastar.WithViewTransitionSelector("#list"),
)
if err != nil {
	log.Printf("patch failed: %v", err)
}
```

--------------------------------

### Run Datastar Go SDK tests

Source: https://github.com/starfederation/datastar-go/blob/main/README.md

Runs all tests in the current directory and its subdirectories.

```bash
go test ./...
```

--------------------------------

### ValidNamespaces slice

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Declares all valid namespaces.

```go
var ValidNamespaces = []Namespace{
	NamespaceHTML,
	NamespaceSVG,
	NamespaceMathML,
}
```

--------------------------------

### Console convenience method signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Signatures for ConsoleLog, ConsoleLogf, and ConsoleError methods.

```go
func (sse *ServerSentEventGenerator) ConsoleLog(msg string, opts ...ExecuteScriptOption) error
func (sse *ServerSentEventGenerator) ConsoleLogf(format string, args ...any) error
func (sse *ServerSentEventGenerator) ConsoleError(err error, opts ...ExecuteScriptOption) error
```

--------------------------------

### Strategy option constructors signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Signatures for the three strategy option constructors: WithClientPriority, WithServerPriority, and WithForced. They set the selection strategy to ClientPriority, ServerPriority, or Forced respectively.

```go
func WithClientPriority() CompressionOption
func WithServerPriority() CompressionOption
func WithForced() CompressionOption
```

--------------------------------

### Redirectf

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Formats a URL using fmt.Sprintf and then executes a client-side redirect.

```APIDOC
## Redirectf

### Description
Formats the URL using `fmt.Sprintf` and then executes a client-side redirect via `setTimeout(() => window.location.href = "<url>")`.

### Method
Function

### Signature
```go
func (sse *ServerSentEventGenerator) Redirectf(format string, args ...any) error
```

### Parameters
- **format** (string) - Required - The format string for the URL.
- **args** (any) - Optional - Arguments to format into the URL.

### Example
```go
sse.Redirectf("/report?year=%d&month=%d", 2024, 6)
```

### Returns
- **error** - An error if the redirect event could not be sent.
```

--------------------------------

### Redirect method signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Signatures for Redirect and Redirectf methods on ServerSentEventGenerator. Redirect executes setTimeout(() => window.location.href = "<url>") and Redirectf formats the URL via fmt.Sprintf first.

```go
func (sse *ServerSentEventGenerator) Redirect(url string, opts ...ExecuteScriptOption) error
func (sse *ServerSentEventGenerator) Redirectf(format string, args ...any) error
```

--------------------------------

### Prefetch method signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

The Go method signature for Prefetch, which takes variadic URL strings and returns an error.

```go
func (sse *ServerSentEventGenerator) Prefetch(urls ...string) error
```

--------------------------------

### WithBrotli

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Appends a Brotli Compressor with configurable quality and sliding window size. Use WithBrotliLevel and WithBrotliLGWin to customize.

```APIDOC
## WithBrotli

### Description
Appends a Brotli Compressor with encoding `brotli.Encoding`. Default quality is `brotli.DefaultCompression`.

### Function
`func WithBrotli(opts ...BrotliOption) CompressionOption`

### Parameters
#### Options
- **WithBrotliLevel(level int)** - Optional - Sets the quality; fastest is `0`, best is `11`. Defaults to `6`.
- **WithBrotliLGWin(lgwin int)** - Optional - Sets the sliding window size (select a value between `10` and `24`). Defaults to `0` (automatic).

### Example
```go
datastar.WithBrotli(datastar.WithBrotliLevel(11))
```
```

--------------------------------

### Console Convenience Methods

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Convenience methods for logging messages to the browser console.

```APIDOC
## Console Convenience Methods

### Description
Convenience methods for logging messages to the browser console.

### Signatures
```go
func (sse *ServerSentEventGenerator) ConsoleLog(msg string, opts ...ExecuteScriptOption) error
func (sse *ServerSentEventGenerator) ConsoleLogf(format string, args ...any) error
func (sse *ServerSentEventGenerator) ConsoleError(err error, opts ...ExecuteScriptOption) error
```

### Methods
- `ConsoleLog`: executes `console.log(<quoted msg>)`.
- `ConsoleLogf`: formats then calls `ConsoleLog`.
- `ConsoleError`: executes `console.error(<quoted err.Error()>)`.

### Example
```go
sse.ConsoleLogf("User %s signed in", user.Name)
sse.ConsoleError(someErr)
```
```

--------------------------------

### NewSSE(w, r, opts ...SSEOption)

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/configuration.md

Creates a new SSE stream. Sets the headers Cache-Control: no-cache, Content-Type: text/event-stream, and (HTTP/1.x only) Connection: keep-alive. Options can override the stream context and enable compression.

```APIDOC
## NewSSE(w, r, opts ...SSEOption)

### Description
Creates a new SSE stream. Sets the headers `Cache-Control: no-cache`, `Content-Type: text/event-stream`, and (HTTP/1.x only) `Connection: keep-alive`. Options can override the stream context and enable compression.

### Method
N/A (function)

### Endpoint
N/A (function)

### Parameters
- **w** (http.ResponseWriter) - Required - The HTTP response writer.
- **r** (*http.Request) - Required - The HTTP request.
- **opts** (...SSEOption) - Optional - A variadic list of options.

### Options
- **WithContext** - Overrides the stream context; default is `r.Context()`.
- **WithCompression** - Sets `Content-Encoding` when an algorithm is selected.

### Response
#### Success Response
- **Headers** - `Cache-Control: no-cache`, `Content-Type: text/event-stream`, and (HTTP/1.x only) `Connection: keep-alive`.

### Example
```go
sse := NewSSE(w, r, WithCompression(CompressionGzip))
```
```

--------------------------------

### NamespaceFromString function signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Converts a string to a Namespace. Accepts "html", "svg", "mathml". Returns the matching constant or an error formatted as fmt.Errorf("invalid namespace: %s", s).

```go
func NamespaceFromString(s string) (Namespace, error)
```

--------------------------------

### ExecuteScript

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Runs a script in the client browser by sending a <script> element via PatchElements.

```APIDOC
## ExecuteScript

### Description
Runs a script in the client browser by sending a `<script>` element via `PatchElements`.

### Signature
```go
func (sse *ServerSentEventGenerator) ExecuteScript(scriptContents string, opts ...ExecuteScriptOption) error
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| scriptContents | `string` | yes | — | JavaScript body placed inside `<script>...</script>`. |
| opts | `...ExecuteScriptOption` | no | none | Options above. |

Default option values: `RetryDuration: DefaultSseRetryDuration`, `Attributes: []string{}`, `AutoRemove: nil` (treated as auto-remove).

The built element is patched with `WithSelector("body")` and `WithModeAppend()`; an `EventID`/`RetryDuration` are forwarded when set.

### Example — basic
```go
sse := datastar.NewSSE(w, r)
if err := sse.ExecuteScript(`console.log("Hello from server!")`); err != nil {
	log.Printf("execute failed: %v", err)
}
```

### Example — module script that persists
```go
err := sse.ExecuteScript(
	`document.title = "Done";`,
	datastar.WithExecuteScriptAttributes(`type="module"`),
	datastar.WithExecuteScriptAutoRemove(false),
)
```
```

--------------------------------

### Redirect

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Executes a client-side redirect by setting window.location.href to the provided URL.

```APIDOC
## Redirect

### Description
Executes `setTimeout(() => window.location.href = "<url>")` on the client to redirect the browser to the specified URL.

### Method
Function

### Signature
```go
func (sse *ServerSentEventGenerator) Redirect(url string, opts ...ExecuteScriptOption) error
```

### Parameters
- **url** (string) - Required - The URL to redirect to.
- **opts** (ExecuteScriptOption) - Optional - Additional options for the script execution.

### Example
```go
sse.Redirect("/new-page")
```

### Returns
- **error** - An error if the redirect event could not be sent.
```

--------------------------------

### WithExecuteScriptAttributeKVs

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

An alternative to WithExecuteScriptAttributes; even parameters are keys, odd parameters are their values. Formats each pair as `%s="%s"` and panics if the number of arguments is odd.

```APIDOC
## WithExecuteScriptAttributeKVs

### Description
An alternative to `WithExecuteScriptAttributes`; even parameters are keys, odd parameters are their values. Formats each pair as `` `%s="%s"` ``. **Panics** with `"WithExecuteScriptAttributeKVs requires an even number of arguments"` if `len(kvs)` is odd.

### Signature
```go
func WithExecuteScriptAttributeKVs(kvs ...string) ExecuteScriptOption
```

### Parameters
- **kvs** (`...string`) - Optional - Even parameters are keys, odd parameters are their values.

### Example
```go
sse.ExecuteScript(`alert("hi")`, datastar.WithExecuteScriptAttributeKVs("type", "module"))
```

### Source
`datastar/execute-script.go:59`
```

--------------------------------

### Compression Configuration

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/configuration.md

Compression options for NewSSE, including strategy, per-algorithm levels, and default compressor order.

```APIDOC
## Compression Configuration

Compression is enabled via `WithCompression(...CompressionOption)` passed to `NewSSE`.

### Defaults
- **Compression strategy**: `ServerPriority`
- **Default compressor order** (when none supplied): Brotli, Zstd, Gzip, Deflate
- **WithGzip default level**: `gzip.DefaultCompression`
- **WithDeflate default level**: `zlib.DefaultCompression`
- **WithBrotli default quality**: `brotli.DefaultCompression` (6)
- **WithBrotliLGWin default**: `0` (automatic)

### Option Groups

#### Strategy
- **Key**: `WithClientPriority` / `WithServerPriority` / `WithForced`
- **Default**: `ServerPriority`

#### Gzip
- **Key**: `WithGzipLevel`
- **Default**: `gzip.DefaultCompression`

#### Deflate
- **Key**: `WithDeflateLevel`, `WithDeflateDictionary`
- **Default**: `zlib.DefaultCompression`, `nil`

#### Brotli
- **Key**: `WithBrotliLevel`, `WithBrotliLGWin`
- **Default**: quality `6`, lgwin `0`

#### Zstd
- **Key**: (via `zstd.EOption`s)
- **Default**: library defaults

#### Compressor defaults when none given
- **Default**: brotli, zstd, gzip, deflate
```

--------------------------------

### ValidNamespaces

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

A slice of all valid namespaces.

```APIDOC
## ValidNamespaces

### Description
A slice of all valid namespaces.

### Definition
```go
var ValidNamespaces = []Namespace{
	NamespaceHTML,
	NamespaceSVG,
	NamespaceMathML,
}
```

### Source
`datastar/elements-sugar.go:24`
```

--------------------------------

### WithGzip

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Appends a gzip Compressor with configurable compression level. Use WithGzipLevel to set the level.

```APIDOC
## WithGzip

### Description
Appends a gzip Compressor with encoding `gzip.Encoding`. Default level is `gzip.DefaultCompression`.

### Function
`func WithGzip(opts ...GzipOption) CompressionOption`

### Parameters
#### Options
- **WithGzipLevel(level int)** - Optional - Sets the gzip compression level. Valid levels: `gzip.NoCompression`, `gzip.BestSpeed`, `gzip.BestCompression`, `gzip.DefaultCompression`, `gzip.HuffmanOnly`.

### Example
```go
datastar.WithGzip(datastar.WithGzipLevel(gzip.BestCompression))
```
```

--------------------------------

### WithExecuteScriptAttributes signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Returns an ExecuteScriptOption that sets script element attributes. Each attribute should be a complete key="value" pair, written verbatim into the <script> opening tag.

```go
func WithExecuteScriptAttributes(attributes ...string) ExecuteScriptOption
```

--------------------------------

### Compressor

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/types.md

Pairs a `httpcompression.CompressorProvider` with an encoding string. See compression documentation for details.

```APIDOC
## Compressor

### Description
Pairs a `httpcompression.CompressorProvider` with an encoding string. See compression documentation for details.

### Type
`type Compressor struct`

### Fields
- **Encoding** (`string`) - Required - The `Content-Encoding` header value.
- **Compressor** (`httpcompression.CompressorProvider`) - Required - Provider from `CAFxX/httpcompression`.

### Source
`datastar/sse-compression.go:34`
```

--------------------------------

### SSE Action-String Generators

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Generate Datastar backend action attribute strings for embedding in HTML. Each formats a URL with fmt.Sprintf and wraps it in the corresponding action directive.

```APIDOC
## SSE Action-String Generators

### Description
These generate Datastar backend `@get` / `@post` / `@put` / `@patch` / `@delete` action attribute strings for embedding in HTML.

### Signatures
```go
func GetSSE(urlFormat string, args ...any) string
func PostSSE(urlFormat string, args ...any) string
func PutSSE(urlFormat string, args ...any) string
func PatchSSE(urlFormat string, args ...any) string
func DeleteSSE(urlFormat string, args ...any) string
```

### Parameters
- **urlFormat** (string) - Required - The URL format string, used with `fmt.Sprintf`.
- **args** (any) - Optional - Arguments to format into the URL.

### Returns
- **string** - The action string, e.g., `@get('/path')` for GetSSE, `@post('/path')` for PostSSE, etc.

### Example
```go
html := fmt.Sprintf(`<button data-on-click="%s">Go</button>`,
	datastar.GetSSE("/increment?step=%d", 2))
```
```

--------------------------------

### DispatchCustomEvent option constructor signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Signatures for all option constructors for DispatchCustomEvent. Defaults: EventID: "", RetryDuration: DefaultSseRetryDuration, Selector: "document", Bubbles: true, Cancelable: true, Composed: true.

```go
func WithDispatchCustomEventEventID(id string) DispatchCustomEventOption
func WithDispatchCustomEventRetryDuration(retryDuration time.Duration) DispatchCustomEventOption
func WithDispatchCustomEventSelector(selector string) DispatchCustomEventOption
func WithDispatchCustomEventBubbles(bubbles bool) DispatchCustomEventOption
func WithDispatchCustomEventCancelable(cancelable bool) DispatchCustomEventOption
func WithDispatchCustomEventComposed(composed bool) DispatchCustomEventOption
```

--------------------------------

### compressionOptions struct

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

The unexported configuration struct that `CompressionOption` functions mutate. Shown for reference.

```go
type compressionOptions struct {
	CompressionStrategy CompressionStrategy
	ClientEncodings     []string
	Compressors         []Compressor
}
```

--------------------------------

### CompressionStrategy

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/types.md

Strategy for selecting the compression algorithm. See compression documentation for details.

```APIDOC
## CompressionStrategy

### Description
Strategy for selecting the compression algorithm. See compression documentation for details.

### Type
`type CompressionStrategy string`

### Constants
- **ClientPriority** (`"client_priority"`) - Client priority strategy.
- **ServerPriority** (`"server_priority"`) - Server priority strategy.
- **Forced** (`"forced"`) - Forced strategy.

### Source
`datastar/sse-compression.go:16–30`
```

--------------------------------

### Compressor Struct

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/types.md

Pairs a httpcompression.CompressorProvider with an encoding string. The Encoding field holds the Content-Encoding header value, and Compressor is a provider from CAFxX/httpcompression.

```go
type Compressor struct {
	Encoding   string
	Compressor httpcompression.CompressorProvider
}
```

--------------------------------

### DispatchCustomEventOption Constructors

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Option constructors for configuring a custom server-sent event.

```APIDOC
## DispatchCustomEventOption Constructors

### Description
These functions return `DispatchCustomEventOption` values that configure a custom server-sent event. The options control event ID, retry duration, selector, and event behavior flags.

### Functions

#### WithDispatchCustomEventEventID
```go
func WithDispatchCustomEventEventID(id string) DispatchCustomEventOption
```
Sets the event ID. Default is `""`.

#### WithDispatchCustomEventRetryDuration
```go
func WithDispatchCustomEventRetryDuration(retryDuration time.Duration) DispatchCustomEventOption
```
Sets the retry duration. Default is `DefaultSseRetryDuration`.

#### WithDispatchCustomEventSelector
```go
func WithDispatchCustomEventSelector(selector string) DispatchCustomEventOption
```
Replaces the default dispatch target `document` with a CSS selector. If the selector matches multiple elements, the event dispatches from each.

#### WithDispatchCustomEventBubbles
```go
func WithDispatchCustomEventBubbles(bubbles bool) DispatchCustomEventOption
```
Sets whether the event bubbles. Default is `true`. Setting to `false` is equivalent to `event.stopPropagation()` on the client.

#### WithDispatchCustomEventCancelable
```go
func WithDispatchCustomEventCancelable(cancelable bool) DispatchCustomEventOption
```
Sets whether the event is cancelable. Default is `true`. Setting to `false` blocks `event.preventDefault()` on the client.

#### WithDispatchCustomEventComposed
```go
func WithDispatchCustomEventComposed(composed bool) DispatchCustomEventOption
```
Sets whether the event is composed. Default is `true`. Setting to `false` prevents propagation across the shadow DOM boundary.

### Defaults
- `EventID`: `""`
- `RetryDuration`: `DefaultSseRetryDuration`
- `Selector`: `"document"`
- `Bubbles`: `true`
- `Cancelable`: `true`
- `Composed`: `true`
```

--------------------------------

### WithServerPriority

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Sets the compression selection strategy to ServerPriority, meaning the server's configured compressors are prioritized.

```APIDOC
## WithServerPriority

### Description
Sets the selection strategy to `ServerPriority`. This means the server's configured compressors are prioritized when selecting a compression method.

### Signature
```go
func WithServerPriority() CompressionOption
```
```

--------------------------------

### Panic on header flush failure

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

NewSSE panics if flushing headers fails, as documented in the source.

```go
panic(fmt.Sprintf("response writer failed to flush: %v", err))
```

--------------------------------

### WithClientPriority

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Sets the compression selection strategy to ClientPriority, meaning the client's preferred encodings are prioritized.

```APIDOC
## WithClientPriority

### Description
Sets the selection strategy to `ClientPriority`. This means the client's preferred encodings are prioritized when selecting a compression method.

### Signature
```go
func WithClientPriority() CompressionOption
```
```

--------------------------------

### WithUseViewTransitions

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/02-elements.md

Specifies whether to use the View Transitions API when merging elements. The useViewTransition parameter is required and when true, emits 'useViewTransition true'.

```APIDOC
## WithUseViewTransitions

### Description
Specifies whether to use the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) when merging elements.

### Signature
```go
func WithUseViewTransitions(useViewTransition bool) PatchElementOption
```

### Parameters
- **useViewTransition** (`bool`) - Required - When true, emits `useViewTransition true`.

### Source
`datastar/elements.go:71`
```

--------------------------------

### CompressionStrategy Type and Constants

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/types.md

Defines the CompressionStrategy string type and its constants for selecting the compression algorithm. See the compression API reference for details.

```go
type CompressionStrategy string

const (
	ClientPriority CompressionStrategy = "client_priority"
	ServerPriority CompressionStrategy = "server_priority"
	Forced         CompressionStrategy = "forced"
)
```

--------------------------------

### Brotli option types and functions

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Defines the BrotliOption type and the WithBrotliLevel, WithBrotliLGWin, and WithBrotli functions. WithBrotliLevel sets the quality, WithBrotliLGWin sets the sliding window size, and WithBrotli appends a Brotli Compressor with encoding brotli.Encoding. Default quality is brotli.DefaultCompression.

```go
type BrotliOption func(*brotli.Options)

func WithBrotliLevel(level int) BrotliOption
func WithBrotliLGWin(lgwin int) BrotliOption
func WithBrotli(opts ...BrotliOption) CompressionOption
```

--------------------------------

### RemoveElement / RemoveElementf / RemoveElementByID signatures

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Signatures for the three element removal helpers. RemoveElement prepends WithModeRemove() and WithSelector(selector) to the supplied options. RemoveElementf formats the selector then calls RemoveElement. RemoveElementByID calls RemoveElement("#" + id).

```go
func (sse *ServerSentEventGenerator) RemoveElement(selector string, opts ...PatchElementOption) error
func (sse *ServerSentEventGenerator) RemoveElementf(selectorFormat string, args ...any) error
func (sse *ServerSentEventGenerator) RemoveElementByID(id string) error
```

--------------------------------

### ServerSentEventGenerator.PatchElementf

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

A convenience wrapper equivalent to PatchElements(fmt.Sprintf(format, args...)). It formats a string with the given arguments and patches the resulting element.

```APIDOC
## ServerSentEventGenerator.PatchElementf

### Description
A convenience wrapper equivalent to `PatchElements(fmt.Sprintf(format, args...))`. It formats a string with the given arguments and patches the resulting element.

### Signature
```go
func (sse *ServerSentEventGenerator) PatchElementf(format string, args ...any) error
```

### Parameters
- **format** (string) - Required - The format string for the element HTML.
- **args** (...any) - Optional - Arguments to be formatted into the format string.

### Example
```go
name := "Ada"
if err := sse.PatchElementf(`<b id="user">%s</b>`, name); err != nil {
	return err
}
```

### Response
Returns an error if the patch operation fails.
```

--------------------------------

### NamespaceFromString

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Converts a string to a Namespace constant. Accepts "html", "svg", and "mathml".

```APIDOC
## NamespaceFromString

### Description
Converts a string to a `Namespace` constant. Accepts `"html"`, `"svg"`, `"mathml"`. Returns the matching constant or an error if invalid.

### Signature
```go
func NamespaceFromString(s string) (Namespace, error)
```

### Parameters
- **s** (string) - Required - The string to convert to a Namespace.

### Returns
- **Namespace** - The matching Namespace constant.
- **error** - An error if the string is not a valid namespace.

### Errors
- Returns `fmt.Errorf("invalid namespace: %s", s)` for invalid input.

### Source
`datastar/elements-sugar.go:55`
```

--------------------------------

### ElementPatchModeFromString signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/03-elements-sugar.md

Function signature for converting a string to an ElementPatchMode.

```go
func ElementPatchModeFromString(s string) (ElementPatchMode, error)
```

--------------------------------

### WithCompression

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/06-compression.md

Adds compression to the server-sent-event stream. It is an SSEOption passed to NewSSE. It parses the client's Accept-Encoding header, selects a compressor based on the strategy, and wraps the response writer.

```APIDOC
## WithCompression

### Description
Adds compression to the server-sent-event stream. It is an `SSEOption` passed to `NewSSE`. It parses the client's `Accept-Encoding` header, selects a compressor based on the strategy, and wraps the response writer.

### Signature
```go
func WithCompression(opts ...CompressionOption) SSEOption
```

### Parameters
- **opts** (CompressionOption) - Optional - Compression options to configure the compression behavior.

### Behavior
- Parses the client's `Accept-Encoding` header into `ClientEncodings` (splitting on commas, dropping quality `;q=` parameters).
- Default `CompressionStrategy` is `ServerPriority`.
- If no compressors are added, defaults to Brotli, Zstd, Gzip, and Deflate (in that order).
- Selection:
  - `ServerPriority`: iterate server compressors, pick the first whose encoding also appears in the client's list.
  - `ClientPriority`: iterate client encodings, pick the first that has a matching server compressor.
  - `Forced`: use the first configured compressor unconditionally.
- On match, wraps the response writer (`sse.w = comp.Compressor.Get(sse.w)`), sets `sse.encoding`, and sets the `Content-Encoding` header inside `NewSSE`.

### Example
```go
sse := datastar.NewSSE(w, r,
	datastar.WithCompression(
		datastar.WithGzip(datastar.WithGzipLevel(gzip.BestCompression)),
		datastar.WithBrotli(),
		datastar.WithClientPriority(),
	),
)
```
```

--------------------------------

### ServerSentEventGenerator.Context method signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Signature for the Context method on ServerSentEventGenerator. Returns the context associated with the upgraded connection.

```go
func (sse *ServerSentEventGenerator) Context() context.Context
```

--------------------------------

### WithExecuteScriptAttributes

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/05-execute-script.md

Sets the script element attributes. Each attribute should be a complete key="value" pair (e.g. `type="module"`).

```APIDOC
## WithExecuteScriptAttributes

### Description
Sets the script element attributes. Each attribute should be a complete `key="value"` pair (e.g. `` `type="module"` ``).

### Signature
```go
func WithExecuteScriptAttributes(attributes ...string) ExecuteScriptOption
```

### Parameters
- **attributes** (`...string`) - Optional - Written verbatim into the `<script ...>` opening tag.

### Source
`datastar/execute-script.go:51`
```

--------------------------------

### NewSSE

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Upgrades an http.ResponseWriter to a server-sent-event stream. Sets appropriate headers, applies options, and flushes headers.

```APIDOC
## NewSSE

### Description
Upgrades an `http.ResponseWriter` to a server-sent-event stream. Sets `Cache-Control: no-cache` and `Content-Type: text/event-stream` headers, and for HTTP/1.x requests also sets `Connection: keep-alive`. Applies provided options and flushes headers.

### Method
Constructor

### Signature
```go
func NewSSE(w http.ResponseWriter, r *http.Request, opts ...SSEOption) *ServerSentEventGenerator
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| w | `http.ResponseWriter` | yes | — | The response writer to stream over. |
| r | `*http.Request` | yes | — | The request that spawned the connection; its `Context()` becomes the SSE stream context. |
| opts | `...SSEOption` | no | none | Initialization options (e.g. `WithContext`, `WithCompression`). |

### Behavior
- Sets `Cache-Control: no-cache` and `Content-Type: text/event-stream` headers.
- For HTTP/1.x requests (`r.ProtoMajor == 1`) also sets `Connection: keep-alive`.
- Builds the generator with the request context, a fresh mutex, `shouldLogPanics: true`, and the request's `Accept-Encoding` header.
- Applies all provided options.
- If a compression encoding was configured (via `WithCompression`), sets the `Content-Encoding` header.
- Flushes headers via `http.NewResponseController(w).Flush()`.

### Panics
`NewSSE` deliberately panics on header flush failure:
```
panic(fmt.Sprintf("response writer failed to flush: %v", err))
```

### Example — basic use
```go
package main

import (
	"log"
	"net/http"
	"time"

	"github.com/starfederation/datastar-go/datastar"
)

func handler(w http.ResponseWriter, r *http.Request) {
	sse := datastar.NewSSE(w, r)

	for i := 0; i < 5; i++ {
		if err := sse.PatchElements(`<div id="tick">tick ` + time.Now().String() + `</div>`); err != nil {
			return
		}
		time.Sleep(time.Second)
	}
}

func main() {
	http.HandleFunc("/stream", handler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```
```

--------------------------------

### WithContext function signature

Source: https://github.com/starfederation/datastar-go/blob/main/_autodocs/api-reference/01-sse-core.md

Signature for WithContext, which returns an SSEOption. The context must be derived from the request context.

```go
func WithContext(ctx context.Context) SSEOption
```
Tokens:
Raw