wasm

func AddClass ¶

func AddClass(id, className string)

func AddEventListener ¶

func AddEventListener(el JSValue, event string, fn func())

AddEventListener attaches a persistent event listener to el for the given event name. fn is called with no arguments each time the event fires. The listener stays alive for the lifetime of the page — it is never removed automatically.

Common use cases: reacting to browser events (click, input, toggle) or framework events (htmx:afterSwap, htmx:beforeSwap) on any JSValue element including Document() and Window().

Example:

body := Document().Get("body")
AddEventListener(body, "htmx:afterSwap", func() {
    // re-sync DOM after HTMX swaps content
})

details := QuerySelector("details#menu")
AddEventListener(details, "toggle", func() {
    // react to open/close state changes
})

func AddEventListenerWithEvent ¶

func AddEventListenerWithEvent(el JSValue, event string, fn func(JSValue))

AddEventListenerWithEvent attaches a persistent event listener to el for the given event name. fn receives the browser Event object as a JSValue, giving access to event properties and methods. Use this when you need to inspect or interact with the event itself — call preventDefault, read event.target, event.key, event.clientX, event.detail, etc. The listener stays alive for the lifetime of the page — it is never removed automatically.

Example:

AddEventListenerWithEvent(form, "submit", func(e JSValue) {
    e.Call("preventDefault")               // stop the default form submission
    val := e.Get("target").Get("value").String()
})

AddEventListenerWithEvent(Document(), "keydown", func(e JSValue) {
    if e.Get("key").String() == "Escape" {
        // close modal, etc.
    }
})

func AppendChild ¶

func AppendChild(parent, child JSValue)

Element tree helpers — server-side no-ops.

func CaptureScope ¶

func CaptureScope() string

CaptureScope returns the scope active at the call site (server-side no-op: always ""). In the WASM runtime it captures the active [data-gothic-scope] so a goroutine can re-establish it with RunInScope when its work runs later — a goroutine does not inherit the scope across a suspension point.

scope := CaptureScope()
go func() { RunInScope(scope, func() { SetText("out", result) }) }()

func ClickElement ¶

func ClickElement(el JSValue)

func ConsoleLog ¶

func ConsoleLog(args ...any)

func CookieDelete ¶

func CookieDelete(key string)

func CookieGet ¶

func CookieGet(key string) string

func CookieSet ¶

func CookieSet(key, value string, opts ...CookieOptions)

Cookie helpers — server-side no-ops.

func CopyBytesToGo ¶

func CopyBytesToGo(dst []byte, src JSValue) int

func CopyBytesToJS ¶

func CopyBytesToJS(dst JSValue, src []byte) int

func CreateTopic ¶

func CreateTopic[T any](zero T, cfg TopicConfig) func() interface{}

CreateTopic declares a topic. The CLI AST scanner detects this call and generates the concrete typed accessor. Server-side this is a no-op stub.

func CreateWasmBoolFunc ¶

func CreateWasmBoolFunc(name string, fn func(bool))

func CreateWasmFunc ¶

func CreateWasmFunc(name string, fn func())

func CreateWasmStringFunc ¶

func CreateWasmStringFunc(name string, fn func(string))

func Decode ¶ added in v1.4.0

func Decode[T any](r Response) (T, error)

Decode parses r's JSON body into a value of struct type T and returns it (server-side no-op: returns the zero value and nil). At WASM build time the gothic CLI REPLACES each Decode[T](resp) call with a generated, reflection-free _jsonDecode_T(resp): the CLI reads T's fields (and json tags) via go/types and emits code that reads them out of the runtime's reflection-free JSON parse — so NEITHER reflect NOR encoding/json is pulled into the TinyGo binary. This server-side stub exists only so a ClientSideState block calling Decode[T] type-checks during SSR / ScanPages.

T must be a struct type. Fields are matched by json tag (falling back to the Go field name); JSON numbers coerce to numeric fields (int64 magnitudes above 2^53 lose precision), and a missing key or JSON null yields the field's zero value. Nested structs, slices, pointers, and string-keyed maps are supported; unsupported field types decode as their zero value.

Example:

resp, err := Fetch("/api/user/1")
if err == nil && resp.OK() {
    user, err := Decode[User](resp)
    if err == nil { SetText("name", user.Name) }
}

func DurableKey ¶

func DurableKey() string

DurableKey returns the placement's stable durable key (data-gothic-durable-key) or "" when not durable (server-side no-op: always ""). In the WASM runtime it reads the attribute off the component wrapper so DurableObserve can rehydrate from the full-Go core across a teardown→re-mount.

func DurableObserve ¶

func DurableObserve[T any](field string, obs *Observable[T], encode func(T) string, decode func(string) T)

DurableObserve binds an observable to the core's page-session durable cache under `field` so its value SURVIVES the component's teardown→re-mount (server-side no-op). OPT-IN: when the placement has no durable key it does nothing and the observable behaves exactly as a plain one — so SSR output is identical whether or not a component opts into durability. encode/decode are the field's string codec (same shape as CustomKey).

count := CreateObservable(0)
DurableObserve("count", count, strconv.Itoa,
    func(s string) int { n, _ := strconv.Atoi(s); return n })

func Encode ¶ added in v1.4.0

func Encode[T any](v T) []byte

Encode marshals a value of struct type T to a JSON []byte, for use as a request body (server-side no-op: returns nil). It is the write-direction mirror of Decode. At WASM build time the gothic CLI REPLACES each Encode[T](v) call with a generated, reflection-free _jsonEncode_T(v): the CLI reads T's fields (and json tags) via go/types and emits code that appends their JSON by hand — so NEITHER reflect NOR encoding/json is pulled into the TinyGo binary. This server-side stub exists only so a ClientSideState block calling Encode[T] type-checks during SSR / ScanPages.

T must be a struct type, and the call MUST carry an explicit type argument (Encode[T](v)) — the build-time rewrite is syntactic and cannot recover an inferred T. Fields are emitted in struct order, keyed by json tag (falling back to the field name); `json:"-"` is skipped; `,omitempty` is ignored (the field is always written); nil slices/pointers/maps become JSON null.

Example:

body := Encode[CreateUser](CreateUser{Name: name})
Fetch("/api/users", FetchConfig{Method: "POST", BodyBytes: body})

func ExecJS ¶

func ExecJS(script string)

ExecJS executes a JavaScript snippet in the browser. Server-side no-op.

func ExtractRuntime ¶

func ExtractRuntime(destDir string) error

ExtractRuntime writes the embedded WASM runtime source files into destDir so TinyGo can compile against them. The resulting layout is:

destDir/
  go.mod          (module wasm-runtime, go 1.21)
  runtime/
    signal.go
    effect.go
    ...

The caller is responsible for removing destDir when the build is done.

func FetchAsync ¶ added in v1.4.0

func FetchAsync(url string, cfg FetchConfig, done func(Response, error))

FetchAsync makes an HTTP request and invokes done(Response, error) when it completes, without blocking (server-side no-op). done runs inside the scope active at the call site so DOM writes hit the right subtree, and the request is aborted on component teardown. Use it when a blocking Fetch would stall a handler.

Example:

FetchAsync("/api/todos", FetchConfig{}, func(resp Response, err error) {
    if err == nil && resp.OK() {
        SetText("out", resp.Text())
    }
})

func FetchChan ¶ added in v1.4.0

func FetchChan(url string, cfg ...FetchConfig) <-chan FetchResult

FetchChan makes an HTTP request and returns a receive-only channel that yields exactly one FetchResult when it completes (server-side no-op mirror). It does not block — select on the returned channel. Use it to await one of several requests or to combine a fetch with a timeout in a select.

Example:

select {
case r := <-FetchChan("/api/todos"):
    if r.Err == nil && r.Response.OK() { SetText("out", r.Response.Text()) }
}

func GetFileBytes ¶

func GetFileBytes(id string) []byte

GetFileBytes reads the contents of the first file selected in a <input type="file"> element. Returns nil if the element is not found, no file is selected, or reading fails.

func GetValue ¶

func GetValue(id string) string

func GoBack ¶

func GoBack()

func LocalStorageGet ¶

func LocalStorageGet(key string) string

func LocalStorageRemove ¶

func LocalStorageRemove(key string)

func LocalStorageSet ¶

func LocalStorageSet(key, value string)

LocalStorage helpers — server-side no-ops.

func Navigate ¶

func Navigate(url string)

Navigation helpers — server-side no-ops.

func OnUnmount ¶

func OnUnmount(fn func()) func()

OnUnmount registers a cleanup callback run when the component's [data-gothic-scope] element is removed from the DOM (server-side no-op). In the WASM runtime it releases things created outside the component's subtree (document listeners, timers, topic mounts, in-flight fetch AbortControllers). It returns a deregister func (a no-op here) that drops the callback early once it becomes dead weight — callers may ignore it.

func PushState ¶

func PushState(url, title string)

func Reload ¶

func Reload()

func RemoveClass ¶

func RemoveClass(id, className string)

func RemoveElement ¶

func RemoveElement(el JSValue)

func RunInScope ¶

func RunInScope(id string, fn func())

RunInScope runs fn with the given scope active, restoring the previous scope afterwards (server-side no-op: fn is not executed, matching Observe). Pair it with CaptureScope to carry a scope into a goroutine or deferred callback.

func SessionStorageGet ¶

func SessionStorageGet(key string) string

func SessionStorageRemove ¶

func SessionStorageRemove(key string)

func SessionStorageSet ¶

func SessionStorageSet(key, value string)

SessionStorage helpers — server-side no-ops.

func SetAttr ¶

func SetAttr(id, attr, value string)

func SetHTML ¶

func SetHTML(id, html string)

func SetStyle ¶

func SetStyle(id, property, value string)

func SetText ¶

func SetText(id, value string)

func SetValue ¶

func SetValue(id, value string)

func ToggleClass ¶

func ToggleClass(id, className string)

func TriggerDownload ¶

func TriggerDownload(filename string, data []byte, mimeType string)

TriggerDownload prompts the browser to download `data` as a file named `filename` with the given MIME type. Server-side no-op.

func WriteClipboard ¶

func WriteClipboard(text string)

WriteClipboard writes text to the system clipboard. Server-side no-op.