elm-ssr 0.2.0 → 0.3.0

package/docs/loaders-and-actions.md

@@ -1,241 +0,0 @@
-# Loaders and Actions
-
-`Loader` and `Action` are **descriptions of work**, not side effects. The
-author composes them; the runtime pumps the actual IO through the Worker's
-effect adapter and feeds the results back until each one terminates.
-
-This keeps Elm pure end-to-end — no manual ports, no flag-shaped JSON
-threading, no `Cmd` for server work.
-
-## Loader (data fetching, for `page`)
-
-A `Loader a` resolves to a value of type `a` after the runtime has executed
-any effects it requested. The page can then render based on that value.
-
-### Constructors
-
-```elm
--- pure success
-Loader.succeed : a -> Loader a
-
--- abort with an HTTP status and message
-Loader.fail : Int -> String -> Loader a
-```
-
-### Composition
-
-```elm
-Loader.map     : (a -> b) -> Loader a -> Loader b
-Loader.map2    : (a -> b -> c) -> Loader a -> Loader b -> Loader c
-Loader.andThen : (a -> Loader b) -> Loader a -> Loader b
-```
-
-Loaders are sequential. `andThen` runs the next effect only after the prior
-one resolves.
-
-### Effects
-
-See [Effects](effects.md) for the full vocabulary. Quick reference:
-
-```elm
-Loader.fetchJson : { url : String, decoder : Decoder a } -> Loader a
-Loader.cacheGet  : { key : String, decoder : Decoder a } -> Loader (Maybe a)
-Loader.cachePut  : { key : String, value : Value, ttlSeconds : Maybe Int } -> Loader ()
-Loader.query     : { sql : String, params : List Value, decoder : Decoder a } -> Loader (List a)
-Loader.queryOne  : { sql : String, params : List Value, decoder : Decoder a } -> Loader (Maybe a)
-Loader.execute   : { sql : String, params : List Value } -> Loader { rowsAffected : Int }
-Loader.env       : String -> Loader (Maybe String)
-Loader.enqueue   : { task : String, payload : Value } -> Loader ()
-```
-
-`getCookie` is also available via `Loader` — see [Effects](effects.md).
-
-### Example: cache → fetch → cache
-
-```elm
-cachedStatus : Loader Status
-cachedStatus =
-    Loader.cacheGet { key = "status", decoder = statusDecoder }
-        |> Loader.andThen
-            (\cached ->
-                case cached of
-                    Just status ->
-                        Loader.succeed status
-
-                    Nothing ->
-                        Loader.fetchJson
-                            { url = "https://api.example.com/status"
-                            , decoder = statusDecoder
-                            }
-                            |> Loader.andThen
-                                (\status ->
-                                    Loader.cachePut
-                                        { key = "status"
-                                        , value = encodeStatus status
-                                        , ttlSeconds = Just 60
-                                        }
-                                        |> Loader.map (\_ -> status)
-                                )
-            )
-```
-
-## Action (form handling, for `action`)
-
-`Action a` is the non-GET equivalent. It can resolve to a value, fail, redirect
-(303-style Post/Redirect/Get), or respond with JSON.
-
-### Constructors
-
-```elm
-Action.succeed  : a -> Action a
-Action.fail     : Int -> String -> Action a
-Action.redirect : String -> Action a
-Action.json     : Value -> Action a
-```
-
-### Cookies
-
-Any `Action` can attach `Set-Cookie` headers to its response — including
-redirects, JSON responses, and even failures. Cookies travel through
-`map`/`andThen`/`fromLoader` so you can compose freely.
-
-```elm
-Action.Cookie : { name : String, value : String, maxAge : Maybe Int, expires : Maybe String, domain : Maybe String, path : Maybe String, secure : Bool, httpOnly : Bool, sameSite : Maybe SameSite }
-
-Action.SameSite = Lax | Strict | None
-
--- Build a cookie:
-Action.defaultCookie : String -> String -> Cookie    -- permissive (Path=/), fill in what you need
-Action.sessionCookie : String -> String -> Cookie    -- HARDENED: Secure, HttpOnly, SameSite=Lax, Max-Age=7d
-
--- Attach to an action:
-Action.setCookie   : Cookie -> Action a -> Action a
-Action.clearCookie : { name : String, path : Maybe String, domain : Maybe String } -> Action a -> Action a
-```
-
-**Security defaults matter.** `Action.sessionCookie` is what you should reach
-for any time a cookie grants authority (session IDs, auth tokens). It sets:
-
-- `HttpOnly` — JavaScript cannot read it (XSS-resistant).
-- `Secure` — only sent over HTTPS.
-- `SameSite=Lax` — sent on top-level navigations, blocked on cross-site
-  sub-requests (CSRF-resistant for unsafe verbs).
-- `Path=/`, `Max-Age=7 days`.
-
-`Action.defaultCookie` is the unopinionated escape hatch for non-sensitive
-cookies (preferences, analytics consent, etc).
-
-### Example: login (PRG + hardened session cookie)
-
-```elm
-action : Request -> Action (Document Never)
-action request =
-    case Route.formValue "username" request of
-        Just username ->
-            Action.fromLoader (mintSessionToken username)
-                |> Action.andThen
-                    (\token ->
-                        Action.redirect "/dashboard"
-                            |> Action.setCookie (Action.sessionCookie "session" token)
-                    )
-
-        Nothing ->
-            Action.fail 422 "Username is required"
-```
-
-### Example: logout
-
-```elm
-action _ =
-    Action.redirect "/login"
-        |> Action.clearCookie { name = "session", path = Just "/", domain = Nothing }
-```
-
-### Reading cookies back
-
-From the matching `page` (or any `Loader`), use `Loader.getCookie`:
-
-```elm
-page _ =
-    Loader.getCookie "session"
-        |> Loader.andThen
-            (\session ->
-                case session of
-                    Just token ->
-                        Loader.map renderDashboard (lookupUser token)
-
-                    Nothing ->
-                        Loader.succeed renderLoginPrompt
-            )
-```
-
-### Stacking multiple cookies
-
-`setCookie` is composable — call it more than once to attach multiple
-cookies to the same response:
-
-```elm
-Action.redirect "/onboarding/step-2"
-    |> Action.setCookie (Action.sessionCookie "session" token)
-    |> Action.setCookie ({ defaultCookie "onboarding" "step-2" | sameSite = Just Lax })
-```
-
-### Local dev gotcha
-
-`Secure` cookies are rejected by modern browsers on plain `http://`. If
-you're hitting your app on `http://localhost`, either run it over HTTPS
-(wrangler dev does, by default) or override `secure = False` on the cookie.
-See [examples/basic/src/Example/Basic/Routes/Session.elm](../examples/basic/src/Example/Basic/Routes/Session.elm)
-for the pattern.
-
-### Composition
-
-```elm
-Action.map     : (a -> b) -> Action a -> Action b
-Action.andThen : (a -> Action b) -> Action a -> Action b
-
--- Lift any Loader (and all its effects: cacheGet, query, execute, env, ...)
--- into an Action so it runs as part of the action's effect chain.
-Action.fromLoader : Loader a -> Action a
-```
-
-`fromLoader` is how actions do server work — there's no separate "action
-effect" type; the entire `Loader` effect vocabulary is reusable.
-
-### Example: a guestbook POST (PRG pattern)
-
-```elm
-action : Request -> Action (Document Never)
-action request =
-    case Route.formValue "message" request of
-        Nothing ->
-            Action.fail 422 "Message is required."
-
-        Just message ->
-            if String.isEmpty (String.trim message) then
-                Action.fail 422 "Message is required."
-
-            else
-                Action.fromLoader
-                    (Loader.execute
-                        { sql = "INSERT INTO entries (message) VALUES (?)"
-                        , params = [ Encode.string message ]
-                        }
-                    )
-                    |> Action.andThen (\_ -> Action.redirect "/guestbook")
-```
-
-The client `POST /guestbook`s with the form, the row is inserted, the action
-redirects with `303 See Other` to `/guestbook`, the browser issues a `GET`, the
-page re-renders with the new entry. No JS required.
-
-## Failures
-
-Both `Loader.fail` and `Action.fail` take an HTTP status. The runtime turns
-them into the matching response (with the message). Decode failures during
-`fetchJson`/`cacheGet`/`query` map to `502` automatically.
-
-## What next
-
-- [Effects](effects.md) — the full effect surface and what each kind does.
-- [Backends](backends.md) — choosing/composing the adapter that runs effects.

package/docs/middleware.md

@@ -1,93 +0,0 @@
-# Middleware
-
-`createWorkerApp` wraps the request handler in a fixed stack of middlewares.
-You usually don't need to touch this — the defaults give you request IDs,
-timing headers, structured request logging, error normalization, and HEAD
-support out of the box.
-
-## Default stack
-
-In order (outermost first):
-
-1. **`errorMiddleware`** — catches anything thrown downstream, logs
-   `elm_ssr_request_failed { requestId, path, error }`, and returns
-   `{ "error": "internal_error", "requestId": ... }` (JSON, status 500) for
-   `/api/*` or plain `Internal Server Error` (status 500) for everything
-   else.
-2. **`requestIdMiddleware`** — uses the incoming `x-request-id` header if
-   non-empty; otherwise generates a fresh UUID. Echoes the value back in the
-   response header.
-3. **`timingMiddleware`** — adds `server-timing: app;dur=…` and
-   `x-response-time: …ms` based on `performance.now() - context.startedAt`.
-4. **`loggingMiddleware`** — after the response is built, logs a JSON line
-   `{ event: "request_completed", requestId, method, path, status, durationMs }`.
-   On Cloudflare the logging is scheduled via `ctx.waitUntil` so it doesn't
-   block the response.
-5. **`headMiddleware`** — for `HEAD` requests, strips the response body while
-   preserving status + headers.
-
-## Composing your own
-
-```ts
-import {
-  composeMiddleware,
-  errorMiddleware,
-  requestIdMiddleware,
-  timingMiddleware,
-  loggingMiddleware,
-  headMiddleware,
-  type Middleware
-} from "elm-ssr/middleware";
-
-const authMiddleware: Middleware = async (context, next) => {
-  if (context.url.pathname.startsWith("/admin/")) {
-    const session = context.request.headers.get("cookie") ?? "";
-    if (!session.includes("admin=1")) {
-      return new Response("Forbidden", { status: 403 });
-    }
-  }
-  return next(context);
-};
-
-const handler = composeMiddleware(myRouteHandler, [
-  errorMiddleware,
-  requestIdMiddleware,
-  timingMiddleware,
-  loggingMiddleware(),
-  authMiddleware,
-  headMiddleware
-]);
-```
-
-`composeMiddleware(handler, [a, b, c])` runs `a` outermost: `a → b → c →
-handler → c → b → a`.
-
-If you want to customize the **default** stack used by `createWorkerApp`,
-you can't drop middlewares from it directly — pass your own `log` to override
-the logger, or build your own `WorkerHandler` from scratch with
-`composeMiddleware` if you need different ordering.
-
-## `AppContext`
-
-Every middleware and handler receives an `AppContext`:
-
-```ts
-interface AppContext {
-  request: Request;
-  url: URL;
-  requestId: string;        // set by requestIdMiddleware (empty before)
-  startedAt: number;        // performance.now() at request start
-  executionCtx?: WorkerExecutionContext;  // present on Cloudflare; has waitUntil
-  env?: Record<string, unknown>;          // Cloudflare bindings
-}
-```
-
-`executionCtx?.waitUntil(promise)` is how the logging and task adapters
-schedule work after the response. If absent (Bun, tests), middlewares fall
-back to fire-and-forget.
-
-## Source
-
-- [packages/elm-ssr/src/middleware.ts](../packages/elm-ssr/src/middleware.ts)
-- [packages/elm-ssr/src/http.ts](../packages/elm-ssr/src/http.ts) — types
-- [packages/elm-ssr/src/app.ts](../packages/elm-ssr/src/app.ts) — default stack

package/docs/migrations.md

@@ -1,143 +0,0 @@
-# SQL migrations
-
-A small, backend-neutral, transactional SQL-file migration runner. Files live
-in a directory (e.g. `migrations/0001_init.sql`), get applied in alphabetical
-order, and are tracked in `__elm_ssr_migrations(name PRIMARY KEY, applied_at)`.
-
-The runner is also wired into the CLI as
-[`elm-ssr migrate up|down|status`](cli.md).
-
-## Files
-
-```
-migrations/
-  0001_init.sql
-  0001_init.down.sql      # optional, paired for `migrate down`
-  0002_add_users.sql
-  0002_add_users.down.sql
-```
-
-- Numeric prefix → alphabetical sort matches creation order.
-- `.down.sql` is optional but required if you want to revert that migration.
-- The runner ignores any non-`.sql` files and ignores `.down.sql` on the up
-  pass.
-
-## Safety
-
-Each migration runs inside a single `BEGIN…COMMIT` transaction **together
-with** its tracking insert. If the SQL fails, the transaction rolls back and
-the tracking row is never written, so the next run picks up exactly where
-this one stopped.
-
-Backends with native transaction support can override this by providing
-`runInTransaction(fn)` on the adapter. The Postgres adapter the CLI ships
-uses `sql.begin(fn)` for proper transactional safety; SQLite uses raw
-`BEGIN`/`COMMIT`.
-
-## CLI
-
-```sh
-elm-ssr migrate up                         # Apply all pending
-elm-ssr migrate down                       # Revert the most recent
-elm-ssr migrate down --count 3             # Revert the last 3
-elm-ssr migrate status                     # Show applied (with timestamps) + pending
-
-# Connection string options:
-elm-ssr migrate up --db postgres://user:pass@localhost:5432/db
-elm-ssr migrate up --db sqlite://./app.db
-elm-ssr migrate up --db ./app.db           # bare path = SQLite
-
-# Reads DATABASE_URL if --db is omitted.
-DATABASE_URL=postgres://... elm-ssr migrate up
-
-# Other flags:
-elm-ssr migrate up --dir ./db/migrations   # default: ./migrations
-elm-ssr migrate up --table schema_history  # default: __elm_ssr_migrations
-```
-
-## Programmatic API
-
-```ts
-import {
-  runMigrations,
-  revertMigrations,
-  listMigrations,
-  type MigrationsAdapter
-} from "elm-ssr/migrations";
-
-// Adapter shape — wire any backend:
-interface MigrationsAdapter {
-  exec(sql: string): Promise<void>;                              // multi-statement, no params
-  list(sql: string): Promise<Array<Record<string, unknown>>>;    // query
-  runInTransaction?(fn: () => Promise<void>): Promise<void>;     // optional native txn
-}
-```
-
-### bun:sqlite
-
-```ts
-import { Database } from "bun:sqlite";
-
-const db = new Database("./app.db");
-const adapter: MigrationsAdapter = {
-  exec: async (sql) => { db.exec(sql); },
-  list: async (sql) => db.query(sql).all() as Array<Record<string, unknown>>
-};
-
-await runMigrations(adapter, { dir: "./migrations" });
-```
-
-### Postgres (Bun.sql)
-
-```ts
-import { SQL } from "bun";
-
-const sql = new SQL(process.env.DATABASE_URL!);
-const adapter: MigrationsAdapter = {
-  exec: async (text) => { await sql.unsafe(text); },
-  list: async (text) => {
-    const rows = await sql.unsafe(text);
-    return Array.isArray(rows) ? rows : [...(rows ?? [])];
-  },
-  runInTransaction: async (fn) => { await sql.begin(fn); }
-};
-
-await runMigrations(adapter, { dir: "./migrations" });
-```
-
-### D1 (Cloudflare)
-
-D1 doesn't expose multi-statement `exec` with `runInTransaction`, so use one
-statement per migration file and run from a scheduled Worker or a build step.
-
-## Return values
-
-```ts
-type MigrationResult = { applied: string[]; skipped: string[] };
-type RevertResult    = { reverted: string[] };
-type MigrationsStatus = {
-  applied: Array<{ name: string; appliedAt: string }>;
-  pending: string[];
-};
-```
-
-## What you can rely on
-
-- **Idempotent.** Re-running `up` skips anything already in
-  `__elm_ssr_migrations`.
-- **Forward-only by default.** `down` errors loudly if the paired
-  `.down.sql` is missing.
-- **Safe failure.** A throwing migration rolls back (assuming a transactional
-  backend); the tracking row is never written.
-- **Custom table name.** Pass `tableName` if `__elm_ssr_migrations` clashes
-  with anything. The name is validated against
-  `^[A-Za-z_][A-Za-z0-9_]*$` to prevent SQL injection via the option.
-
-## Source
-
-- [packages/elm-ssr/src/migrations.ts](../packages/elm-ssr/src/migrations.ts)
-- [packages/elm-ssr/lib/migrate.mjs](../packages/elm-ssr/lib/migrate.mjs)
-- Tests:
-  [test/migrations.test.ts](../test/migrations.test.ts),
-  [test/cli-migrate.test.ts](../test/cli-migrate.test.ts),
-  [test/integration/redis-postgres.test.ts](../test/integration/redis-postgres.test.ts)

package/docs/routing.md

@@ -1,108 +0,0 @@
-# Routing
-
-Routing is file-based, Next/Remix-style. The CLI scans
-`src/<Namespace>/Routes/` and generates a router that dispatches by URL path
-and HTTP method.
-
-## File layout → URL
-
-| File | URL |
-| ---- | --- |
-| `Routes/Index.elm` | `/` |
-| `Routes/About.elm` | `/about` |
-| `Routes/Posts/Index.elm` | `/posts` |
-| `Routes/Posts/Slug_.elm` | `/posts/:slug` (dynamic) |
-| `Routes/Greet/Name_.elm` | `/greet/:name` |
-| `Routes/NotFound.elm` | fallback for everything else |
-
-Trailing-underscore names are **dynamic segments**, captured into
-`Request.params` and read with `Route.param "slug"`.
-
-## Every route exposes `page` and `action`
-
-```elm
-module Demo.Routes.About exposing (page, action)
-
-import ElmSsr.Action as Action exposing (Action)
-import ElmSsr.Document exposing (Document)
-import ElmSsr.Html exposing (p, text)
-import ElmSsr.Loader as Loader exposing (Loader)
-import ElmSsr.Page as Page
-import ElmSsr.Route exposing (Request)
-
-
-page : Request -> Loader (Document Never)
-page _ =
-    Loader.succeed view
-
-
-action : Request -> Action (Document Never)
-action _ =
-    Action.fail 405 "Method not allowed"
-
-
-view : Document Never
-view =
-    Page.page
-        { title = "About"
-        , head = []
-        , body = [ p [] [ text "About this app" ] ]
-        }
-```
-
-- `page` handles `GET` and `HEAD`. Returns a `Loader (Document Never)`.
-- `action` handles `POST` (and other non-GET). Returns an
-  `Action (Document Never)`. Most pages reject non-GET with `Action.fail 405`.
-
-See [Loaders and Actions](loaders-and-actions.md) for the data-fetching side.
-
-## Reading the request
-
-```elm
-import ElmSsr.Route as Route exposing (Request)
-
-
-page : Request -> Loader (Document Never)
-page request =
-    case Route.param "slug" request of
-        Just slug ->
-            -- dynamic segment captured from the filename
-            loadPost slug
-
-        Nothing ->
-            Loader.fail 400 "Missing slug"
-```
-
-`ElmSsr.Route` exports:
-- `method : Request -> String` — uppercased HTTP method.
-- `segments : Request -> List String` — path split into non-empty parts.
-- `query : String -> Request -> Maybe String` — query-string parameter.
-- `param : String -> Request -> Maybe String` — dynamic route segment.
-- `params : Request -> List ( String, String )` — all dynamic segments.
-- `formValue : String -> Request -> Maybe String` — form field, for actions.
-
-## NotFound
-
-`Routes/NotFound.elm` is the fallback. Use `Page.notFound` (which sets the
-right status) instead of `Page.page`:
-
-```elm
-view : Document Never
-view =
-    Page.notFound
-        { title = "Not found"
-        , head = []
-        , body = [ p [] [ text "This route does not exist." ] ]
-        }
-```
-
-If you don't ship a `NotFound.elm`, unknown routes get a plain text 404 from
-the runtime.
-
-## Tips
-
-- Keep route modules small. Move shared markup into `View/Shared.elm`.
-- For a static (no-data) page, `Loader.succeed view` is enough — no effects
-  are pumped.
-- For interactive bits inside a page, embed an island. The page itself stays
-  SSR-only; only the island ships JS. See [Islands](islands.md).