Side-effects for hyper actions.
Provides escape hatches for actions that need to do more than mutate cursors/signals. Most action logic should use cursors (the UI is a pure function of state), but some operations genuinely require side-effects that can't be expressed as state:
navigate! — client-side route change (pushState) from an actionset-cookie! — set an HTTP cookie on the action responsedelete-cookie! — remove an HTTP cookieexecute-script! — run arbitrary JS on the client via SSEend-session! — end the session, signing out its open tabsrotate-session! — give the session a new idThese are intentionally few. If you're reaching for execute-script! to update UI, consider whether a cursor would be more appropriate.
Effects are accumulated during action execution in a dynamic var and processed by the action handler after the action completes. Cookies are applied to the HTTP response; scripts are sent via SSE.
Example: (require '[hyper.effects :as effects])
;; Navigate after saving (h/action (save-post! data) (effects/navigate! :post-detail {:id 123}))
;; Set a cookie (h/action (when (authenticate! user pass) (effects/set-cookie! "auth" jwt {:http-only true :max-age 86400}) (effects/navigate! :dashboard)))
;; Run client-side JS (use sparingly) (h/action (effects/execute-script! "document.getElementById('search').focus()"))
Side-effects for hyper actions.
Provides escape hatches for actions that need to do more than mutate
cursors/signals. Most action logic should use cursors (the UI is a
pure function of state), but some operations genuinely require
side-effects that can't be expressed as state:
- `navigate!` — client-side route change (pushState) from an action
- `set-cookie!` — set an HTTP cookie on the action response
- `delete-cookie!` — remove an HTTP cookie
- `execute-script!` — run arbitrary JS on the client via SSE
- `end-session!` — end the session, signing out its open tabs
- `rotate-session!` — give the session a new id
These are intentionally few. If you're reaching for execute-script!
to update UI, consider whether a cursor would be more appropriate.
Effects are accumulated during action execution in a dynamic var and
processed by the action handler after the action completes. Cookies
are applied to the HTTP response; scripts are sent via SSE.
Example:
(require '[hyper.effects :as effects])
;; Navigate after saving
(h/action
(save-post! data)
(effects/navigate! :post-detail {:id 123}))
;; Set a cookie
(h/action
(when (authenticate! user pass)
(effects/set-cookie! "auth" jwt {:http-only true :max-age 86400})
(effects/navigate! :dashboard)))
;; Run client-side JS (use sparingly)
(h/action
(effects/execute-script! "document.getElementById('search').focus()"))(delete-cookie! name)(delete-cookie! name opts)Delete an HTTP cookie from within an action.
Sets the cookie with an empty value and max-age 0, which instructs the browser to remove it.
name: Cookie name string opts: Optional map — typically :path must match the original cookie's path
Example: (h/action (effects/delete-cookie! "auth") (effects/navigate! :login))
Delete an HTTP cookie from within an action.
Sets the cookie with an empty value and max-age 0, which instructs
the browser to remove it.
name: Cookie name string
opts: Optional map — typically :path must match the original cookie's path
Example:
(h/action
(effects/delete-cookie! "auth")
(effects/navigate! :login))(end-session!)End the session of the action's tab once the action has run.
The session and its data are removed, the session cookie is deleted, and every open page of the session reconnects and reloads into a fresh session. A page loaded with the old id gets a new session, as with any session cookie the server does not know. Does nothing when the session is already gone.
Example: ;; Sign out (h/action (effects/delete-cookie! "auth") (effects/end-session!))
End the session of the action's tab once the action has run.
The session and its data are removed, the session cookie is deleted, and
every open page of the session reconnects and reloads into a fresh
session. A page loaded with the old id gets a new session, as with any
session cookie the server does not know. Does nothing when the session
is already gone.
Example:
;; Sign out
(h/action
(effects/delete-cookie! "auth")
(effects/end-session!))(execute-script! js)Execute JavaScript on the client from within an action.
The script is sent via SSE as a Datastar execute-script event. A tab whose connection dropped gets it when it reconnects. Use sparingly — most UI updates are better expressed as cursor mutations that the render function responds to.
Legitimate uses: focusing an element, scrolling to a position, triggering a file download, clipboard operations.
js: JavaScript string to execute in the browser
Example: (h/action (effects/execute-script! "document.getElementById('search').focus()"))
(h/action (effects/execute-script! "window.scrollTo(0, 0)"))
Execute JavaScript on the client from within an action.
The script is sent via SSE as a Datastar execute-script event. A tab
whose connection dropped gets it when it reconnects.
Use sparingly — most UI updates are better expressed as cursor
mutations that the render function responds to.
Legitimate uses: focusing an element, scrolling to a position,
triggering a file download, clipboard operations.
js: JavaScript string to execute in the browser
Example:
(h/action
(effects/execute-script! "document.getElementById('search').focus()"))
(h/action
(effects/execute-script! "window.scrollTo(0, 0)"))(navigate! route-name)(navigate! route-name params)(navigate! route-name params query-params)Navigate to a named route from within an action.
Performs the server-side route transition (updates render-fn and route
state, which triggers a re-render via SSE) and queues a pushState
call to update the browser URL bar. Sets the client's navigating?*
signal before the new route renders.
route-name: Keyword name of the route params: Optional map of path parameters query-params: Optional map of query parameters
Example: (h/action (let [post (save-post! data)] (effects/navigate! :post-detail {:id (:id post)})))
(h/action (effects/navigate! :search {} {:q "clojure"}))
Navigate to a named route from within an action.
Performs the server-side route transition (updates render-fn and route
state, which triggers a re-render via SSE) and queues a pushState
call to update the browser URL bar. Sets the client's `navigating?*`
signal before the new route renders.
route-name: Keyword name of the route
params: Optional map of path parameters
query-params: Optional map of query parameters
Example:
(h/action
(let [post (save-post! data)]
(effects/navigate! :post-detail {:id (:id post)})))
(h/action
(effects/navigate! :search {} {:q "clojure"}))(rotate-session!)Give the session of the action's tab a new id once the action has run,
keeping its data and its tabs, and set the session cookie to the new id.
Once the action's response has been written, the session's open pages
reconnect: in the person's own browser they carry the new cookie and go
on with their tab state, and in a browser that still holds the old id
they reload into a fresh session. The old id names no session
afterwards. end-session! in the same action takes precedence.
Throws in code run by hyper.core/run-in-tabs!: the server can't tell
which browser each of the session's tabs is in, so only the person's own
action or route (hyper.ring/rotate-session!) can hand the new id to
their browser alone.
Example: ;; Sign in (h/action (when-let [user (authenticate! @email* @password*)] (reset! (h/session-cursor :user) user) (effects/rotate-session!)))
Give the session of the action's tab a new id once the action has run,
keeping its data and its tabs, and set the session cookie to the new id.
Once the action's response has been written, the session's open pages
reconnect: in the person's own browser they carry the new cookie and go
on with their tab state, and in a browser that still holds the old id
they reload into a fresh session. The old id names no session
afterwards. `end-session!` in the same action takes precedence.
Throws in code run by `hyper.core/run-in-tabs!`: the server can't tell
which browser each of the session's tabs is in, so only the person's own
action or route (`hyper.ring/rotate-session!`) can hand the new id to
their browser alone.
Example:
;; Sign in
(h/action
(when-let [user (authenticate! @email* @password*)]
(reset! (h/session-cursor :user) user)
(effects/rotate-session!)))(set-cookie! name value)(set-cookie! name value opts)Set an HTTP cookie from within an action.
The cookie will be added to the action's HTTP response via Set-Cookie headers. This is the only way to set cookies from hyper — the SSE channel cannot carry Set-Cookie headers.
name: Cookie name string value: Cookie value string opts: Optional map of cookie options: :path — Cookie path (default "/") :max-age — Max age in seconds :http-only — Boolean, prevent JS access (default false) :secure — Boolean, HTTPS only (default false) :same-site — :strict, :lax, or :none
Example: (h/action (when-let [token (authenticate! user pass)] (effects/set-cookie! "auth" token {:http-only true :secure true :max-age (* 60 60 24 7)})))
Set an HTTP cookie from within an action.
The cookie will be added to the action's HTTP response via Set-Cookie
headers. This is the only way to set cookies from hyper — the SSE
channel cannot carry Set-Cookie headers.
name: Cookie name string
value: Cookie value string
opts: Optional map of cookie options:
:path — Cookie path (default "/")
:max-age — Max age in seconds
:http-only — Boolean, prevent JS access (default false)
:secure — Boolean, HTTPS only (default false)
:same-site — :strict, :lax, or :none
Example:
(h/action
(when-let [token (authenticate! user pass)]
(effects/set-cookie! "auth" token {:http-only true
:secure true
:max-age (* 60 60 24 7)})))cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |