OctaStar (octa_star v0.1.0)

Elixir SDK helpers for Datastar.

The facade functions in this module delegate to small protocol modules while keeping a pipeline-friendly Plug API:

conn
|> OctaStar.start()
|> OctaStar.patch_signals(%{count: 1})
|> OctaStar.patch_elements(~s(<div id="count">1</div>))

Summary

Functions

__using__(atom)

Provides Phoenix controller helpers.

check_connection(conn)

Checks whether a chunked SSE connection still accepts writes.

console_log(conn, message, opts \\ [])

Logs a value to the browser console.

execute_script(conn, script, opts \\ [])

Executes JavaScript in the browser by appending a script element.

patch_elements(conn, elements, opts \\ [])

Patches one or more complete HTML elements into the DOM.

patch_signals(conn, signals, opts \\ [])

Patches client-side Datastar signals using RFC 7386 JSON Merge Patch semantics.

patch_signals_raw(conn, signals_json, opts \\ [])

Patches client-side Datastar signals from a pre-encoded JSON string.

read_signals(conn)

Reads Datastar signals from a Plug connection.

read_signals!(conn)

Reads Datastar signals from a Plug connection, raising on invalid JSON.

redirect(conn, url, opts \\ [])

Redirects the browser by executing a tiny client-side script.

remove_elements(conn, selector, opts \\ [])

Removes elements from the DOM by CSS selector.

remove_signals(conn, paths, opts \\ [])

Removes signals by setting one or more dot-notated signal paths to null.

send(conn, event_type, data_lines, opts \\ [])

Sends a raw Datastar SSE event and returns the updated connection.

start(conn)

Starts a Server-Sent Events response on a Plug connection.

start_stream(conn, scope_key)

Starts an SSE stream with per-tab deduplication.

Functions

using(atom)

(macro)

Provides Phoenix controller helpers.

Use use OctaStar, :controller in your AppWeb.controller/0 macro instead of use OctaStar.Phoenix.Controller directly:

def controller do
  quote do
    use Phoenix.Controller, formats: [:html]
    use OctaStar, :controller
  end
end

check_connection(conn)

@spec check_connection(Plug.Conn.t()) ::
  {:ok, Plug.Conn.t()} | {:error, Plug.Conn.t()}

Checks whether a chunked SSE connection still accepts writes.

console_log(conn, message, opts \\ [])

@spec console_log(Plug.Conn.t(), term(), keyword()) :: Plug.Conn.t()

Logs a value to the browser console.

execute_script(conn, script, opts \\ [])

@spec execute_script(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()

Executes JavaScript in the browser by appending a script element.

patch_elements(conn, elements, opts \\ [])

@spec patch_elements(Plug.Conn.t(), iodata() | tuple() | nil, keyword()) ::
  Plug.Conn.t()

Patches one or more complete HTML elements into the DOM.

patch_signals(conn, signals, opts \\ [])

@spec patch_signals(Plug.Conn.t(), map(), keyword()) :: Plug.Conn.t()

Patches client-side Datastar signals using RFC 7386 JSON Merge Patch semantics.

patch_signals_raw(conn, signals_json, opts \\ [])

@spec patch_signals_raw(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()

Patches client-side Datastar signals from a pre-encoded JSON string.

read_signals(conn)

@spec read_signals(Plug.Conn.t()) :: map()

Reads Datastar signals from a Plug connection.

Returns a signal map. Raises OctaStar.Signals.ReadError when the payload cannot be decoded. Plugs that need {:ok, map()} | {:error, term()} should call OctaStar.Signals.read/1 instead.

read_signals!(conn)

@spec read_signals!(Plug.Conn.t()) :: map()

Reads Datastar signals from a Plug connection, raising on invalid JSON.

redirect(conn, url, opts \\ [])

@spec redirect(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()

Redirects the browser by executing a tiny client-side script.

remove_elements(conn, selector, opts \\ [])

@spec remove_elements(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()

Removes elements from the DOM by CSS selector.

remove_signals(conn, paths, opts \\ [])

@spec remove_signals(Plug.Conn.t(), String.t() | [String.t()], keyword()) ::
  Plug.Conn.t()

Removes signals by setting one or more dot-notated signal paths to null.

send(conn, event_type, data_lines, opts \\ [])

@spec send(Plug.Conn.t(), String.t(), [String.t()] | String.t(), keyword()) ::
  Plug.Conn.t()

Sends a raw Datastar SSE event and returns the updated connection.

start(conn)

@spec start(Plug.Conn.t()) :: Plug.Conn.t()

Starts a Server-Sent Events response on a Plug connection.

start_stream(conn, scope_key)

@spec start_stream(Plug.Conn.t(), term()) :: Plug.Conn.t()

Starts an SSE stream with per-tab deduplication.

Requires OctaStar.Utility.StreamRegistry in your supervision tree and a tabId signal in your root layout. See OctaStar.Utility.StreamRegistry for setup.