ds

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package ds holds the Datastar adapter, S12.

It provides the server sent event stream, the element patch, the signal patch and the script helper. It renders a component into the stream, so a page and a patch share one template.

The frames follow the Datastar SDK specification of version 1.0. That version carries two events: datastar-patch-elements and datastar-patch-signals. It carries no execute script event, so ExecuteScript patches a script element into the body, which is the shape that the specification states.

The package is an optional import. The view package does not import it, and the scaffolded ui package does not import it. A component reads Partial and renders a fragment, so one template serves both shapes. See the SDD, S12.

Index

Constants

View Source
const (
	// EventPatchElements patches elements into the document.
	EventPatchElements = "datastar-patch-elements"
	// EventPatchSignals patches values into the signal store.
	EventPatchSignals = "datastar-patch-signals"
)

The names of the Datastar events. See the Datastar SDK specification, version 1.0.

View Source
const (
	// RequestHeader marks a request that Datastar made.
	RequestHeader = "Datastar-Request"
	// SignalsParam carries the signals of a GET request.
	SignalsParam = "datastar"
)

The names that Datastar sends on a request.

View Source
const MaxSignals = 1 << 20

MaxSignals is the largest signal body that ReadSignals reads.

Variables

View Source
var ErrClosed = sse.ErrClosed

ErrClosed states that the client closed the stream. A patch returns it after a disconnect, so the handler stops and the goroutine ends.

Functions

func Open

func Open(fn func(s *Stream) error) router.Response

Open returns a Response that opens a server sent event stream and runs fn.

The handler holds the request until fn returns, so fn must select on Done. A disconnect makes every patch return ErrClosed, so a loop that ignores Done still ends.

r.Get("/updates", func(c *router.Ctx) (router.Response, error) {
    return ds.Open(func(s *ds.Stream) error {
        for {
            select {
            case <-s.Done():
                return nil
            case row := <-rows:
                if err := s.PatchElements(views.Row(row)); err != nil {
                    return err
                }
            }
        }
    }), nil
})

func Partial

func Partial(c *router.Ctx) bool

Partial reports whether Datastar made this request. A component renders one fragment for a partial request and the whole page for any other.

func ReadSignals

func ReadSignals(c *router.Ctx, v any) error

ReadSignals fills v from the signals of the request. A GET request carries them in the datastar query parameter, and any other method carries them in the body as JSON.

var in struct{ Count int `json:"count"` }
if err := ds.ReadSignals(c, &in); err != nil {
    return nil, err
}

Types

type Fault

type Fault struct {
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
}

Fault is one Datastar fault. It states what went wrong and states the repair in one sentence. See DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the message and the repair.

type Mode

type Mode string

Mode states how a patch places its elements.

const (
	// ModeOuter replaces the element that the selector names.
	ModeOuter Mode = "outer"
	// ModeInner replaces the children of the element.
	ModeInner Mode = "inner"
	// ModeReplace replaces the element and keeps no attribute.
	ModeReplace Mode = "replace"
	// ModePrepend puts the elements before the first child.
	ModePrepend Mode = "prepend"
	// ModeAppend puts the elements after the last child.
	ModeAppend Mode = "append"
	// ModeBefore puts the elements before the element.
	ModeBefore Mode = "before"
	// ModeAfter puts the elements after the element.
	ModeAfter Mode = "after"
	// ModeRemove removes the element that the selector names.
	ModeRemove Mode = "remove"
)

The modes of an element patch. The default is outer, which the frame omits.

type Option

type Option func(*patch)

Option configures one element patch.

func WithMode

func WithMode(m Mode) Option

WithMode states how the patch places its elements. The default is outer.

func WithSelector

func WithSelector(selector string) Option

WithSelector names the element that the patch changes. An empty selector leaves the placement to the identifier of the elements.

func WithViewTransition

func WithViewTransition() Option

WithViewTransition asks the browser for a view transition.

type SignalOption

type SignalOption func(*signals)

SignalOption configures one signal patch.

func WithOnlyIfMissing

func WithOnlyIfMissing() SignalOption

WithOnlyIfMissing keeps a signal that the store already holds.

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream writes Datastar frames to one client.

func (*Stream) Ctx

func (s *Stream) Ctx() *router.Ctx

Ctx returns the request that opened the stream.

func (*Stream) Done

func (s *Stream) Done() <-chan struct{}

Done returns a channel that closes when the client disconnects.

select {
case <-s.Done():
    return nil
case row := <-rows:
    return s.PatchElements(rows.View(row))
}

func (*Stream) ExecuteScript

func (s *Stream) ExecuteScript(script string, opts ...Option) error

ExecuteScript runs a script in the browser.

Version 1.0 of the Datastar specification carries no execute script event. The script becomes a script element that the patch appends to the body, and the effect attribute removes the element after it runs.

func (*Stream) PatchElements

func (s *Stream) PatchElements(c view.Component, opts ...Option) error

PatchElements renders a component and patches it into the document.

The component is a templ component or any other view.Component, so a page and a patch share one template.

func (*Stream) PatchHTML

func (s *Stream) PatchHTML(html string, opts ...Option) error

PatchHTML patches markup into the document. PatchElements renders a component and calls it.

func (*Stream) PatchSignals

func (s *Stream) PatchSignals(v any, opts ...SignalOption) error

PatchSignals encodes v as JSON and patches it into the signal store.

return s.PatchSignals(map[string]any{"count": n})

func (*Stream) RemoveElements

func (s *Stream) RemoveElements(selector string) error

RemoveElements removes every element that the selector names.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL