elm-ssr 0.2.0 → 0.3.0

package/docs/cli.md

@@ -1,117 +0,0 @@
-# CLI
-
-The `elm-ssr` command. Installed when you `bun add elm-ssr`, run as
-`bun elm-ssr <command>` in a workspace or `npx elm-ssr <command>`.
-
-## Commands
-
-### `elm-ssr build`
-
-Reads `elm-ssr.config.json`, then for each configured app:
-
-1. Scans `src/<Namespace>/Routes/` and `Islands/`.
-2. Generates `<root>/.elm-ssr/Main.elm` (the router; file-based routes +
-   dynamic segments) and the islands manifest.
-3. Syncs the Elm authoring modules from
-   `packages/elm-ssr/elm-src/ElmSsr/*.elm` into
-   `<root>/.elm-ssr/src/ElmSsr/`.
-4. Runs `elm make` to compile the page program + one combined island bundle
-   (`Elm.<App>.Islands.<Name>` per island).
-
-Outputs land in `generated/<app-name>/` (gitignored).
-
-### `elm-ssr compress`
-
-Same pipeline as `build`, but additionally gzips the generated bundles so the
-edge can serve `Content-Encoding: gzip` directly.
-
-### `elm-ssr dev`
-
-```sh
-elm-ssr dev
-```
-
-Runs `build` then `wrangler dev`. Use this for local Cloudflare-flavoured
-development.
-
-### `elm-ssr new <name>`
-
-```sh
-elm-ssr new my-app
-```
-
-Scaffolds a new app under `examples/<name>/` and registers it in
-`elm-ssr.config.json`. Generates `Routes/Index.elm`, `Routes/Counter.elm`,
-`Routes/NotFound.elm`, `Islands/Counter.elm`, `View/Shared.elm`, plus the
-TypeScript `runtime.ts`, `worker.ts`, `styles.ts`, and `elm.json`.
-
-Name must match `^[a-z0-9-]+$` (lowercase letters, digits, dashes).
-
-### `elm-ssr migrate <up|down|status>`
-
-SQL-file migration runner. See [docs/migrations.md](migrations.md) for
-behaviour. Quick reference:
-
-```sh
-elm-ssr migrate up                                # apply pending
-elm-ssr migrate down                              # revert most recent
-elm-ssr migrate down --count 3
-elm-ssr migrate status                            # applied + pending
-
-elm-ssr migrate up --db postgres://user:pass@host:5432/db
-elm-ssr migrate up --db sqlite://./app.db
-elm-ssr migrate up --db ./app.db                  # bare path = SQLite
-
-elm-ssr migrate up --dir ./db/migrations          # default ./migrations
-elm-ssr migrate up --table schema_history         # default __elm_ssr_migrations
-```
-
-Reads `DATABASE_URL` from the environment if `--db` is omitted.
-
-### `elm-ssr routes`
-
-Prints each configured app with its module + routes directory.
-
-```sh
-$ elm-ssr routes
-basic: root=examples/basic module=Example.Basic routes=src/Example/Basic/Routes
-```
-
-### `elm-ssr info`
-
-Prints the workspace package name + the list of configured app names.
-
-### `elm-ssr help`
-
-Default when no command is given. Lists everything.
-
-## Global flag
-
-`--root <path>` overrides where the CLI looks for `elm-ssr.config.json` and
-treats as the workspace root. Default: current working directory.
-
-## Configuration
-
-`elm-ssr.config.json` at the workspace root lists your apps:
-
-```jsonc
-{
-  "apps": [
-    { "name": "basic",           "root": "examples/basic",           "module": "Example.Basic" },
-    { "name": "crypto-dashboard","root": "examples/crypto-dashboard","module": "CryptoDashboard" }
-  ]
-}
-```
-
-- `name` — short identifier; used in `generated/<name>/` paths.
-- `root` — the app's directory (relative to the workspace root).
-- `module` — the root Elm namespace (period-separated). `Example.Basic`
-  expects `src/Example/Basic/Routes/`, `src/Example/Basic/Islands/`, etc.
-
-## Source
-
-- Entry point: [packages/elm-ssr/bin/elm-ssr.mjs](../packages/elm-ssr/bin/elm-ssr.mjs)
-- Build: [packages/elm-ssr/lib/build.mjs](../packages/elm-ssr/lib/build.mjs)
-- Scaffold: [packages/elm-ssr/lib/scaffold.mjs](../packages/elm-ssr/lib/scaffold.mjs)
-- Migrate: [packages/elm-ssr/lib/migrate.mjs](../packages/elm-ssr/lib/migrate.mjs)
-- Workspace config: [packages/elm-ssr/lib/workspace.mjs](../packages/elm-ssr/lib/workspace.mjs)

package/docs/effects.md

@@ -1,91 +0,0 @@
-# Effects
-
-Effects are the **single, backend-neutral vocabulary** that loaders and
-actions speak. Elm describes what it needs (`{ kind, payload }`); the Worker's
-configured adapter executes it against a real backend (KV/D1, Redis/Postgres,
-in-memory map, …). This is what lets the same Elm code run on Cloudflare and
-locally without change.
-
-## The vocabulary
-
-All effects are available on `Loader`. Actions reuse them via
-`Action.fromLoader`.
-
-| Elm function | `kind` string | What it does |
-| ------------ | ------------- | ------------ |
-| `Loader.fetchJson { url, decoder }` | `fetchJson` | HTTP GET, JSON-decoded. |
-| `Loader.cacheGet { key, decoder }` | `cacheGet` | Cache read; returns `Maybe a`. |
-| `Loader.cachePut { key, value, ttlSeconds }` | `cachePut` | Cache write with optional TTL. |
-| `Loader.query { sql, params, decoder }` | `query` | SQL select, decode rows. |
-| `Loader.queryOne { sql, params, decoder }` | `queryOne` | First row only (`Maybe a`). |
-| `Loader.execute { sql, params }` | `execute` | INSERT/UPDATE/DELETE; returns `{ rowsAffected }`. |
-| `Loader.env name` | `env` | Read an env var / binding name. |
-| `Loader.getCookie name` | `cookie` | Read a request cookie (parsed from the `Cookie` header). Returns `Maybe String`. |
-| `Loader.session decoder` | `session` | Read the current session payload (requires `sessionMiddleware`). See [sessions](sessions.md). |
-| `Loader.csrfToken` | `csrfToken` | Read the current CSRF token (requires `sessionMiddleware`). See [sessions](sessions.md). |
-| `Loader.setSession value` | `setSession` | Replace the session payload. Mark dirty for middleware to persist. See [sessions](sessions.md). |
-| `Loader.clearSession` | `clearSession` | Destroy the session. Mark for middleware to delete + clear cookie. See [sessions](sessions.md). |
-| `Loader.enqueue { task, payload }` | `enqueue` | Fire-and-forget background work. See [tasks](tasks.md). |
-
-To **write** a cookie on the response, use `Action.setCookie` /
-`Action.clearCookie` / `Action.sessionCookie` from inside an `Action` — see
-[Loaders and Actions](loaders-and-actions.md#cookies).
-
-## Failure modes
-
-- `fetchJson` non-2xx → `502 fetchJson received <status> from <url>`.
-- `fetchJson` decode failure → `502 Loader response did not match decoder: …`.
-- `cacheGet` / `query…` decode failure → `502` with the decode error.
-- Missing backend (e.g. no SQL adapter wired in `inMemoryEffects`) →
-  `502 The "sql" handler is not configured…`.
-
-Failures are turned into HTTP responses (5xx page or JSON for `/api/`).
-
-## How a `kind` resolves to a backend
-
-The Worker uses an `EffectRunner` you supply (or the default if you supply
-none). Adapters are composable functions of type
-`EffectRunner -> EffectRunner` that intercept the kinds they care about and
-forward everything else.
-
-```ts
-import { inMemoryEffects, cloudflareEffects } from "elm-ssr/effects";
-import { withCache, redisCache, postgresSql } from "elm-ssr/backends";
-import { withTasks } from "elm-ssr/tasks";
-
-// Cloudflare: KV (cacheGet/Put), D1 (query/queryOne/execute), env, cookie, fetchJson.
-const effects = withTasks(
-  cloudflareEffects({ cacheBinding: "CACHE", dbBinding: "DB" }),
-  { sendEmail, warmCache }
-);
-
-// Local: in-memory cache + env + fetchJson, Redis cache, Postgres SQL.
-const effects = withTasks(
-  withCache(
-    inMemoryEffects({ sql: postgresSql(pg), env: { /* … */ } }),
-    redisCache(redis)
-  ),
-  { sendEmail, warmCache }
-);
-```
-
-See [Backends](backends.md) for the adapter catalogue and [Tasks and
-queues](tasks.md) for `enqueue`.
-
-## Defaults if you skip `effects`
-
-The runtime falls back to `defaultEffectRunner`. It handles only:
-- `fetchJson` — real `fetch`.
-- `cookie` — parsed from `request.headers["cookie"]`.
-
-Everything else returns `{ ok: false, error: "Effect \"<kind>\" has no
-configured backend…" }`, which surfaces as a 502 to the caller. So a Loader
-that just calls `fetchJson` works with zero config; one that touches the cache
-or DB needs an adapter.
-
-## What next
-
-- [Backends](backends.md) — assemble an adapter that runs these effects.
-- [Tasks and queues](tasks.md) — what `enqueue` actually does.
-- Source: [packages/elm-ssr/src/effects.ts](../packages/elm-ssr/src/effects.ts),
-  [packages/elm-ssr/elm-src/ElmSsr/Loader.elm](../packages/elm-ssr/elm-src/ElmSsr/Loader.elm).

package/docs/getting-started.md

@@ -1,94 +0,0 @@
-# Getting started
-
-elm-ssr is one package: `elm-ssr`. It ships the CLI, the Worker runtime, the
-Elm authoring modules, and the SQL migration runner. Use it on Cloudflare
-Workers in production or on Bun locally for dev.
-
-## Install
-
-```sh
-bun add elm-ssr
-```
-
-Make sure Bun ≥ 1.3 (`engines.bun` in the package).
-
-## Scaffold a new app
-
-In a fresh workspace, create `elm-ssr.config.json`:
-
-```jsonc
-{
-  "apps": []
-}
-```
-
-Then:
-
-```sh
-bun elm-ssr new my-app
-```
-
-This creates `examples/my-app/` (or whatever you name it) with:
-- `elm.json` — Elm package manifest
-- `runtime.ts` — wires the Worker (`createWorkerApp`)
-- `worker.ts` — entry point (`export default worker`)
-- `styles.ts` — inlined stylesheet
-- `src/<Namespace>/Routes/Index.elm`, `Counter.elm`, `NotFound.elm`
-- `src/<Namespace>/Islands/Counter.elm`
-- `src/<Namespace>/View/Shared.elm`
-
-It also adds the app to `elm-ssr.config.json`.
-
-## Build
-
-```sh
-bun elm-ssr build
-```
-
-For each configured app the CLI:
-1. Scans `src/<Namespace>/Routes/` and `src/<Namespace>/Islands/`.
-2. Generates `<app-root>/.elm-ssr/Main.elm` (the router, with file-based
-   routes + dynamic segments).
-3. Syncs the Elm authoring modules (`ElmSsr/*.elm`) into
-   `<app-root>/.elm-ssr/src/ElmSsr/`.
-4. Runs `elm make` to compile the page program and one combined island bundle
-   (`Elm.<App>.Islands.<Name>` per island).
-
-Outputs land in `generated/<app-name>/` (gitignored).
-
-## Run locally
-
-```sh
-bun elm-ssr dev
-```
-
-That runs `build` then `wrangler dev`. The same Worker handler is used both on
-Bun (via wrangler) and on Cloudflare in production.
-
-## Project layout
-
-```
-elm-ssr.config.json              # Lists your apps
-package.json                     # Workspaces, scripts
-examples/
-  my-app/
-    elm.json
-    runtime.ts                   # createWorkerApp(...)
-    worker.ts                    # export default worker
-    src/MyApp/
-      Routes/
-        Index.elm
-      Islands/
-        Counter.elm
-      View/
-        Shared.elm
-    migrations/                  # Optional: SQL files for `elm-ssr migrate`
-generated/                       # Build output (gitignored)
-```
-
-## What next
-
-- [Routing](routing.md) — adding pages with file-based routes.
-- [Loaders and Actions](loaders-and-actions.md) — fetching data and handling
-  form submissions.
-- [Islands](islands.md) — adding interactive bits to otherwise-static pages.

package/docs/islands.md

@@ -1,197 +0,0 @@
-# Islands
-
-An island is a normal `Browser.element` Elm program that mounts client-side
-into an SSR-rendered page. It uses **stock** `elm/html`, `elm/svg`, `elm/http`,
-`Html.Keyed`, etc. — there is no custom virtual-DOM patcher, no fake
-hydration. The server emits a marker element with encoded flags + optional
-fallback markup; the browser runtime finds the marker and runs the island's
-`main`.
-
-This keeps islands fully compatible with the broader Elm package ecosystem.
-
-## Authoring an island
-
-Islands live under `src/<App>/Islands/`. The build picks them up
-automatically. Each module should expose `embed` (called from pages) plus
-`main` (mounted client-side):
-
-```elm
-module Demo.Islands.Counter exposing (embed, main)
-
-import Browser
-import ElmSsr.Island as Island
-import ElmSsr.Html as SsrHtml
-import ElmSsr.Html.Attributes as SsrAttributes
-import Html exposing (Html, button, div, span, text)
-import Html.Attributes exposing (class)
-import Html.Events exposing (onClick)
-import Json.Encode as Encode
-
-
--- SSR-side: page calls `Counter.embed { start = 0 }`.
-embed : Flags -> Island.Node msg
-embed =
-    Island.embed "Counter"
-        { encodeFlags = \f -> Encode.object [ ( "start", Encode.int f.start ) ]
-        , fallback = \f -> [ SsrHtml.text (String.fromInt f.start) ]
-        , id = Nothing
-        }
-
-
--- Client-side: stock Browser.element with stock elm/html.
-type alias Flags =
-    { start : Int }
-
-
-type alias Model =
-    { count : Int }
-
-
-type Msg
-    = Increment
-    | Decrement
-
-
-main : Program Flags Model Msg
-main =
-    Browser.element
-        { init = \flags -> ( { count = flags.start }, Cmd.none )
-        , update = update
-        , view = view
-        , subscriptions = \_ -> Sub.none
-        }
-
-
-update : Msg -> Model -> ( Model, Cmd Msg )
-update msg model =
-    case msg of
-        Increment -> ( { model | count = model.count + 1 }, Cmd.none )
-        Decrement -> ( { model | count = model.count - 1 }, Cmd.none )
-
-
-view : Model -> Html Msg
-view model =
-    div [ class "counter" ]
-        [ button [ onClick Decrement ] [ text "-" ]
-        , span [] [ text (String.fromInt model.count) ]
-        , button [ onClick Increment ] [ text "+" ]
-        ]
-```
-
-A page embeds the island the same way it would render anything else:
-
-```elm
-import Demo.Islands.Counter as Counter
-
-view : Document Never
-view =
-    Page.page
-        { title = "Counter"
-        , head = []
-        , body = [ Counter.embed { start = 0 } ]
-        }
-```
-
-There is **no `Generated.Islands` re-export.** Authors import island modules
-directly. Codegen is reserved for things the author never touches
-(`Main.elm`, the islands client program, the manifest).
-
-## `Island.embed` and `Config`
-
-```elm
-type alias Config flags pageMsg =
-    { encodeFlags : flags -> Encode.Value
-    , fallback : flags -> List (Node pageMsg)
-    , id : Maybe String
-    }
-
-embed : String -> Config flags pageMsg -> flags -> Node pageMsg
-```
-
-- `name` must match the generated bundle key (the module's basename, e.g.
-  `"Counter"` for `Islands/Counter.elm`).
-- `encodeFlags` serializes the island's flags into the SSR markup; the client
-  runtime decodes them and feeds them to `init`.
-- `fallback` is SSR-only markup shown before the client bundle mounts — show
-  initial server-rendered state, a spinner, or nothing.
-- `id` lets the island **persist across SPA navigation** (see below).
-
-## Pages use `ElmSsr.Html`, islands use `elm/html`
-
-This is the load-bearing convention in this repo:
-
-- A **page** returns `Document Never` and is serialised on the server to
-  HTML. It uses `ElmSsr.Html` because Cloudflare Workers has no DOM, and
-  `elm/html`'s virtual-DOM kernel can't run server-side.
-- An **island** is a normal browser Elm program. Its `view : Model -> Html Msg`
-  uses `Html exposing (...)` from `elm/html`. `ElmSsr.Html` only shows up
-  inside the island module for the `fallback` markup (which is part of the
-  page tree, not the island's runtime).
-
-Don't "fix" an island view to use `ElmSsr.Html` — that's the pre-pivot
-architecture that was deleted.
-
-## Cross-island state
-
-Islands are isolated from each other. To communicate, use
-`ElmSsr.Island.Shared`, which provides a `window` CustomEvent bus.
-
-```elm
-import ElmSsr.Island.Shared as Shared
-
-
--- Send to all other islands:
-update msg model =
-    ( newModel, Shared.broadcast "cart:add" (encodeItem item) )
-
-
--- Listen for broadcasts. A broadcaster also hears its own broadcast —
--- filter by tag in update:
-subscriptions _ =
-    Shared.listen GotGlobalEvent
-
-
-update msg model =
-    case msg of
-        GotGlobalEvent { tag, payload } ->
-            if tag == "cart:add" then ... else (model, Cmd.none)
-```
-
-`GlobalEvent` is `{ tag : String, payload : Value }`.
-
-## Persistence across SPA navigation
-
-When a user clicks an in-app link, the client runtime fetches the new page
-via `/api/render`, swaps `#elm-ssr-root` innerHTML, re-boots islands, and
-syncs the `<head>`. By default, every island re-initializes from its new
-flags.
-
-To **keep an island alive** across navigation, give it an `id`:
-
-```elm
-Island.embed "MiniCart"
-    { encodeFlags = encodeFlags
-    , fallback = ...
-    , id = Just "mini-cart"     -- ← persist
-    }
-```
-
-The runtime transfers the live marker (with its full subtree and Elm runtime
-state) into the new page if a marker with the same `id` is present.
-Non-persistent islands are torn down — their `window` broadcast listeners are
-removed, but Elm has no program teardown, so subscriptions to timers/ports
-continue running until the page reloads. Keep that in mind for long-lived
-non-persistent islands.
-
-## What next
-
-- [Routing](routing.md) — where the page that embeds the island lives.
-- [examples/crypto-dashboard/](../examples/crypto-dashboard/) — islands using
-  `elm/svg`, `elm/http`, `Html.Keyed`, 15s `Time.every` refresh, and the
-  cross-island bus.
-
-## Source
-
-- [packages/elm-ssr/elm-src/ElmSsr/Island.elm](../packages/elm-ssr/elm-src/ElmSsr/Island.elm)
-- [packages/elm-ssr/elm-src/ElmSsr/Island/Shared.elm](../packages/elm-ssr/elm-src/ElmSsr/Island/Shared.elm)
-- [packages/elm-ssr/src/client-runtime/islands.ts](../packages/elm-ssr/src/client-runtime/islands.ts)