Datastar.hs

{- |
Module      : Hypermedia.Datastar
Description : Haskell SDK for building real-time hypermedia apps with Datastar

<https://data-star.dev/ Datastar> is a hypermedia framework: instead of
building a JSON API and a JavaScript SPA, you write HTML on the server and
let Datastar handle the interactivity. The browser sends requests, the
server holds the connection open as a server-sent event (SSE) stream, and
pushes HTML fragments, signal updates, or scripts back to the browser as
things change.

This SDK provides the server-side Haskell API. It builds on
<https://hackage.haskell.org/package/wai WAI> so it works with Warp, Scotty,
Servant, Yesod, or any other WAI-compatible framework.

=== Minimal example

@
import Hypermedia.Datastar
import Network.Wai (Application, responseLBS, requestMethod, pathInfo)
import Network.Wai.Handler.Warp qualified as Warp
import Network.HTTP.Types (status404)

app :: Application
app req respond =
  case (requestMethod req, pathInfo req) of
    (\"GET\", [\"hello\"]) ->
      respond $ sseResponse $ \\gen ->
        sendPatchElements gen (patchElements \"\<div id=\\\"msg\\\"\>Hello!\<\/div\>\")
    _ ->
      respond $ responseLBS status404 [] \"Not found\"

main :: IO ()
main = Warp.run 3000 app
@

=== Module guide

* "Hypermedia.Datastar.PatchElements" — send HTML to morph into the DOM
* "Hypermedia.Datastar.PatchSignals" — update the browser's reactive signals
* "Hypermedia.Datastar.ExecuteScript" — run JavaScript in the browser
* "Hypermedia.Datastar.WAI" — SSE streaming, signal decoding, request helpers
* "Hypermedia.Datastar.Types" — protocol types and defaults

=== Further reading

* <https://data-star.dev/ Datastar homepage> — guides, reference, and examples
* <https://cljdoc.org/d/dev.data-star.clojure/http-kit/1.0.0-RC7/doc/sdk-docs/using-datastar Clojure SDK docs> — excellent Datastar walkthrough that applies across SDKs
-}
module Hypermedia.Datastar
  ( -- * Types
    EventType (..)
  , ElementPatchMode (..)
  , ElementNamespace (..)

    -- * Patch Elements
  , PatchElements (..)
  , patchElements
  , removeElements

    -- * Patch Signals
  , PatchSignals (..)
  , patchSignals

    -- * Execute Script
  , ExecuteScript (..)
  , executeScript

    -- * WAI
  , ServerSentEventGenerator
  , sseResponse
  , sendPatchElements
  , sendPatchSignals
  , sendExecuteScript
  , readSignals
  , isDatastarRequest

    -- * Logger
  , DatastarLogger(..)
  , nullLogger
  , stderrLogger
  )
where

import Hypermedia.Datastar.ExecuteScript (ExecuteScript (..), executeScript)
import Hypermedia.Datastar.PatchElements (PatchElements (..), patchElements, removeElements)
import Hypermedia.Datastar.PatchSignals (PatchSignals (..), patchSignals)
import Hypermedia.Datastar.Types (ElementNamespace (..), ElementPatchMode (..), EventType (..))
import Hypermedia.Datastar.WAI
  ( ServerSentEventGenerator
  , isDatastarRequest
  , readSignals
  , sendExecuteScript
  , sendPatchElements
  , sendPatchSignals
  , sseResponse
  )
import Hypermedia.Datastar.Logger (DatastarLogger, nullLogger, stderrLogger)