elm-ssr 0.2.0 → 0.3.0

package/llms.txt

@@ -1,69 +0,0 @@
-# elm-ssr
-
-> Elm-first SSR library and framework for Cloudflare Workers (and Bun locally).
-> Pages render server-side from a custom serialisable AST (because Workers has
-> no DOM). Islands are stock `Browser.element` programs mounted client-side.
-> A backend-neutral effect surface (cache/sql/env/cookie/fetchJson/enqueue) lets
-> the same Elm code run on Cloudflare KV/D1 or local Redis/Postgres/SQLite by
-> swapping the adapter. Background work via `waitUntil` or Cloudflare Queues.
-> SQL-file migrations bundled. One package, `elm-ssr`, ships CLI + runtime + Elm
-> authoring modules.
-
-## Start here
-
-- [README](README.md): Project overview, quickstart, full authoring example.
-- [CHANGELOG](CHANGELOG.md): What changed in each release.
-- [docs/README.md](docs/README.md): Table of contents for the topic-by-topic
-  docs.
-- [docs/getting-started.md](docs/getting-started.md): Install, scaffold, build,
-  run.
-
-## Core concepts
-
-- [docs/routing.md](docs/routing.md): File-based routing (Routes/, dynamic
-  segments, NotFound).
-- [docs/loaders-and-actions.md](docs/loaders-and-actions.md): `Loader` (data
-  fetching for pages) and `Action` (form handling / non-GET).
-- [docs/effects.md](docs/effects.md): The backend-neutral effect vocabulary
-  (`fetchJson`, `cacheGet/Put`, `query/queryOne/execute`, `env`, `getCookie`,
-  `enqueue`).
-- [docs/islands.md](docs/islands.md): Standard `Browser.element` islands;
-  `Island.embed`; cross-island bus via `ElmSsr.Island.Shared`.
-
-## Runtime / adapters
-
-- [docs/backends.md](docs/backends.md): Composing adapters
-  (`inMemoryEffects`, `cloudflareEffects`, `withCache`, `redisCache`,
-  `postgresSql`).
-- [docs/tasks.md](docs/tasks.md): Background work — `withTasks` (`waitUntil`)
-  and Cloudflare Queues (`withQueueProducer` / `createQueueConsumer`).
-- [docs/migrations.md](docs/migrations.md): SQL-file migration runner
-  (`runMigrations`, `revertMigrations`, `listMigrations`); transactional.
-- [docs/middleware.md](docs/middleware.md): The middleware stack
-  (`composeMiddleware`, requestId, timing, logging, error, HEAD).
-- [docs/sessions.md](docs/sessions.md): Signed-cookie sessions + CSRF.
-  Memory + cache stores. `Loader.session` / `csrfToken` / `setSession` /
-  `clearSession`.
-
-## Tooling
-
-- [docs/cli.md](docs/cli.md): `elm-ssr build|new|migrate|dev|compress|routes`.
-- [docs/testing.md](docs/testing.md): `bun run test` (Docker-managed PG+Redis),
-  `bun run test:unit`, `bun run test:integration`.
-
-## Conventions for AI agents
-
-- [AGENTS.md](AGENTS.md): Hard rules and footguns for LLMs editing this repo.
-  Read this before changing anything — especially the rule that islands use
-  `elm/html`, pages use `ElmSsr.Html`, and there is no `Generated.*` re-export
-  in the author-facing API.
-
-## Source of truth
-
-- TS runtime: [packages/elm-ssr/src/](packages/elm-ssr/src/)
-- CLI scripts: [packages/elm-ssr/lib/](packages/elm-ssr/lib/) (bin entry at
-  [packages/elm-ssr/bin/elm-ssr.mjs](packages/elm-ssr/bin/elm-ssr.mjs))
-- Elm authoring modules: [packages/elm-ssr/elm-src/ElmSsr/](packages/elm-ssr/elm-src/ElmSsr/)
-- Reference app: [examples/basic/](examples/basic/)
-- Crypto dashboard (islands + svg + http + cross-island bus):
-  [examples/crypto-dashboard/](examples/crypto-dashboard/)

package/packages/elm-ssr/README.md

@@ -1,67 +0,0 @@
-# elm-ssr
-
-Elm-first SSR library and framework for Cloudflare Workers (and Bun locally).
-One package, three pieces:
-
-- A **CLI** (`elm-ssr build|new|migrate|dev`) that scans your routes/islands,
-  generates the router + manifest, and runs `elm make`.
-- A **Worker runtime** (`createWorkerApp`, `renderApp`, effect adapters,
-  background tasks, SQL migrations, middleware) exported via subpaths.
-- A set of **Elm authoring modules** under `elm-src/ElmSsr/` (Route, Loader,
-  Action, Html, Svg, Island, Page, Document, Runtime) which the build syncs
-  into each app's `.elm-ssr/src/ElmSsr/`.
-
-## Install
-
-```sh
-bun add elm-ssr
-```
-
-Then use the CLI as `elm-ssr <command>` (or `bun elm-ssr <command>` in a
-workspace) and import the runtime via subpaths.
-
-## CLI commands
-
-- **`elm-ssr build`** — scans each configured app's `src/<Namespace>/Routes/`
-  and `Islands/`, generates `.elm-ssr/Main.elm` (the router with file-based
-  routes + dynamic segments) and the islands manifest, syncs the Elm authoring
-  modules into the app's `.elm-ssr/src/ElmSsr/`, and compiles via `elm make`
-  (one combined island bundle exposing `Elm.<App>.Islands.<Name>`).
-- **`elm-ssr new <name>`** — scaffold a new app and register it in
-  `elm-ssr.config.json`.
-- **`elm-ssr dev`** — `build` then `wrangler dev`.
-- **`elm-ssr compress`** — pre-compress generated bundles with gzip.
-- **`elm-ssr migrate <up|down|status>`** — apply / revert / inspect SQL-file
-  migrations. `--db postgres://…`, `sqlite://path`, or a plain SQLite file path;
-  `--dir <path>` (default `./migrations`); `--count N` (for `down`, default 1).
-  Reads `DATABASE_URL` if `--db` is omitted.
-
-Configuration lives in `elm-ssr.config.json` at the repo root:
-
-```jsonc
-{
-  "apps": [
-    { "name": "basic", "root": "examples/basic", "module": "Example.Basic" }
-  ]
-}
-```
-
-## Runtime exports
-
-```ts
-import { createWorkerApp } from "elm-ssr";
-import { renderApp, type CompiledElmModule } from "elm-ssr/render";
-import type { RouteCatalog } from "elm-ssr/http";
-import { inMemoryEffects, cloudflareEffects } from "elm-ssr/effects";
-import { withCache, redisCache, postgresSql } from "elm-ssr/backends";
-import { withTasks, withQueueProducer, createQueueConsumer } from "elm-ssr/tasks";
-import { runMigrations, revertMigrations, listMigrations } from "elm-ssr/migrations";
-import { composeMiddleware } from "elm-ssr/middleware";
-```
-
-See the [top-level README](../../README.md) for end-to-end usage and the
-authoring guide.
-
-## License
-
-MIT.

package/packages/elm-ssr/package.json

@@ -1,61 +0,0 @@
-{
-  "name": "elm-ssr",
-  "version": "0.2.0",
-  "description": "Elm-first SSR library and framework for Cloudflare Workers (and Bun): file-based routes/islands, backend-neutral effect adapters (KV/D1/Redis/Postgres), background tasks (waitUntil/Queues), SQL-file migrations, CLI scaffold + build.",
-  "license": "MIT",
-  "author": "Michał Majchrzak <michmajchrzak@gmail.com>",
-  "homepage": "https://github.com/the-man-with-a-golden-mind/elm-ssr#readme",
-  "bugs": {
-    "url": "https://github.com/the-man-with-a-golden-mind/elm-ssr/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/the-man-with-a-golden-mind/elm-ssr.git",
-    "directory": "packages/elm-ssr"
-  },
-  "keywords": [
-    "elm",
-    "ssr",
-    "server-side-rendering",
-    "cloudflare-workers",
-    "bun",
-    "islands",
-    "framework",
-    "edge",
-    "file-based-routing",
-    "migrations"
-  ],
-  "type": "module",
-  "scripts": {},
-  "bin": {
-    "elm-ssr": "bin/elm-ssr.mjs"
-  },
-  "main": "./src/app.ts",
-  "exports": {
-    ".": "./src/app.ts",
-    "./render": "./src/render.ts",
-    "./http": "./src/http.ts",
-    "./effects": "./src/effects.ts",
-    "./tasks": "./src/tasks.ts",
-    "./backends": "./src/backends.ts",
-    "./migrations": "./src/migrations.ts",
-    "./middleware": "./src/middleware.ts",
-    "./sessions": "./src/sessions/index.ts",
-    "./response-headers": "./src/response-headers.ts",
-    "./serialize": "./src/serialize.ts",
-    "./protocol": "./src/protocol.ts",
-    "./islands-runtime": "./src/client-runtime/islands.ts"
-  },
-  "files": [
-    "bin",
-    "lib",
-    "elm-src",
-    "src"
-  ],
-  "engines": {
-    "bun": ">=1.3"
-  },
-  "dependencies": {
-    "cookie": "^1.0.1"
-  }
-}

package/scripts/benchmark.mjs

@@ -1,60 +0,0 @@
-import { createExampleWorker, renderPath } from "../examples/basic/runtime.ts";
-
-const worker = createExampleWorker({ log: () => {} });
-
-const quantile = (values, fraction) => {
-  const sorted = [...values].sort((left, right) => left - right);
-  const index = Math.min(sorted.length - 1, Math.floor(sorted.length * fraction));
-  return sorted[index];
-};
-
-const formatMs = (value) => `${value.toFixed(2)} ms`;
-const formatOps = (value) => `${value.toFixed(1)} ops/s`;
-
-const runCase = async (label, iterations, task) => {
-  const samples = [];
-
-  for (let index = 0; index < iterations; index += 1) {
-    const startedAt = performance.now();
-    await task();
-    samples.push(performance.now() - startedAt);
-  }
-
-  const total = samples.reduce((sum, sample) => sum + sample, 0);
-  const avg = total / samples.length;
-  const p95 = quantile(samples, 0.95);
-
-  return {
-    label,
-    iterations,
-    avg,
-    p95,
-    throughput: 1000 / avg
-  };
-};
-
-const cases = [
-  await runCase("renderPath(/)", 75, async () => {
-    await renderPath("/");
-  }),
-  await runCase("renderPath(/counter)", 75, async () => {
-    await renderPath("/counter");
-  }),
-  await runCase("worker.fetch(/api/health)", 150, async () => {
-    const response = await worker.fetch(new Request("https://bench.local/api/health"));
-    await response.text();
-  }),
-  await runCase("worker.fetch(/counter)", 75, async () => {
-    const response = await worker.fetch(new Request("https://bench.local/counter"));
-    await response.text();
-  })
-];
-
-console.log("Elm SSR benchmark");
-console.log("==================");
-
-for (const result of cases) {
-  console.log(
-    `${result.label}\n  iterations: ${result.iterations}\n  avg: ${formatMs(result.avg)}\n  p95: ${formatMs(result.p95)}\n  throughput: ${formatOps(result.throughput)}`
-  );
-}

package/test/action.test.ts

@@ -1,81 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { createExampleWorker, worker } from "../examples/basic/runtime";
-import { inMemoryEffects } from "elm-ssr/effects";
-
-// Phase 2: server Actions. A POST form submission runs the route's action, which
-// validates, performs a server effect, then redirects (Post/Redirect/Get). All
-// of this works with no client JavaScript.
-
-const postEcho = (body: string) =>
-  worker.fetch(
-    new Request("https://example.com/echo", {
-      method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      body
-    })
-  );
-
-describe("server actions (POST -> action -> redirect)", () => {
-  it("runs an effectful action and redirects (PRG), no client JS", async () => {
-    const response = await postEcho("message=hello");
-    expect(response.status).toBe(302);
-    // region comes from the action's server effect, so its presence proves the
-    // effect ran inside the action before the redirect.
-    expect(response.headers.get("location")).toBe("/echo?status=received&region=edge");
-  });
-
-  it("fails validation with 422 when the field is empty", async () => {
-    const response = await postEcho("message=");
-    expect(response.status).toBe(422);
-  });
-
-  it("fails validation with 422 when the field is whitespace only", async () => {
-    const response = await postEcho("message=%20%20");
-    expect(response.status).toBe(422);
-  });
-
-  it("fails validation with 422 when the field is missing", async () => {
-    const response = await postEcho("");
-    expect(response.status).toBe(422);
-  });
-
-  it("renders the form on GET and ships no client JS", async () => {
-    const response = await worker.fetch(new Request("https://example.com/echo"));
-    expect(response.status).toBe(200);
-    const html = await response.text();
-    expect(html).toContain('<form class="echo-form" method="post" action="/echo">');
-    expect(html).toContain('name="message"');
-    expect(html).not.toContain("/__elm-ssr/islands.js");
-  });
-
-  it("shows the confirmation page after the redirect", async () => {
-    const response = await worker.fetch(new Request("https://example.com/echo?status=received&region=edge"));
-    expect(response.status).toBe(200);
-    const html = await response.text();
-    expect(html).toContain("Message received");
-    expect(html).toContain("region: edge");
-  });
-
-  it("still rejects non-POST/GET methods", async () => {
-    const response = await worker.fetch(new Request("https://example.com/echo", { method: "PUT" }));
-    expect(response.status).toBe(405);
-  });
-
-  it("propagates an effect failure from the action's loader (network down -> 502)", async () => {
-    const effects = inMemoryEffects({
-      fetchJson: () => {
-        throw new Error("network down");
-      }
-    });
-    const app = createExampleWorker({ effects });
-
-    const response = await app.fetch(
-      new Request("https://example.com/echo", {
-        method: "POST",
-        headers: { "content-type": "application/x-www-form-urlencoded" },
-        body: "message=hello"
-      })
-    );
-    expect(response.status).toBe(502);
-  });
-});

package/test/adapters.test.ts

@@ -1,173 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { defaultEffectRunner, inMemoryEffects } from "elm-ssr/effects";
-import { postgresSql, redisCache, withCache, type CacheClient, type SqlClient } from "elm-ssr/backends";
-import { createQueueConsumer, withQueueProducer, type QueueBatch } from "elm-ssr/tasks";
-
-// Unit-level coverage for the adapter glue: cookie reading, redisCache over a
-// fake Redis-shaped client, postgresSql over a fake SQL client, and the CF
-// Queue producer + consumer. No external servers needed.
-
-describe("cookie effect (getCookie)", () => {
-  const runEffect = (header: string | null, name: string) =>
-    inMemoryEffects()(
-      { kind: "cookie", payload: { name } },
-      { request: new Request("https://example.com/", { headers: header ? { cookie: header } : {} }) }
-    );
-
-  it("returns the requested cookie value when present", async () => {
-    const result = await runEffect("session=abc; theme=dark", "theme");
-    expect(result).toEqual({ ok: true, value: "dark" });
-  });
-
-  it("returns null when the cookie is absent", async () => {
-    const result = await runEffect("session=abc", "theme");
-    expect(result).toEqual({ ok: true, value: null });
-  });
-
-  it("returns null when no Cookie header is sent", async () => {
-    const result = await runEffect(null, "anything");
-    expect(result).toEqual({ ok: true, value: null });
-  });
-
-  it("URL-decodes the value (default behavior of the cookie parser)", async () => {
-    const result = await runEffect("user=John%20Doe", "user");
-    expect(result).toEqual({ ok: true, value: "John Doe" });
-  });
-});
-
-describe("redisCache + withCache (Redis adapter)", () => {
-  const fakeRedis = (): CacheClient & { store: Map<string, string> } => {
-    const store = new Map<string, string>();
-    return {
-      store,
-      get: async (key) => store.get(key) ?? null,
-      set: async (key, value) => {
-        store.set(key, value);
-      }
-    };
-  };
-
-  it("round-trips cachePut → cacheGet via the client", async () => {
-    const client = fakeRedis();
-    const runner = withCache(defaultEffectRunner, redisCache(client));
-
-    const put = await runner(
-      { kind: "cachePut", payload: { key: "k", value: { hello: "world" } } },
-      {}
-    );
-    expect(put).toEqual({ ok: true, value: null });
-
-    const get = await runner({ kind: "cacheGet", payload: { key: "k" } }, {});
-    expect(get).toEqual({ ok: true, value: { hello: "world" } });
-    // The underlying client received a JSON-encoded string.
-    expect(client.store.get("k")).toBe('{"hello":"world"}');
-  });
-
-  it("returns null on a miss", async () => {
-    const runner = withCache(defaultEffectRunner, redisCache(fakeRedis()));
-    const get = await runner({ kind: "cacheGet", payload: { key: "absent" } }, {});
-    expect(get).toEqual({ ok: true, value: null });
-  });
-
-  it("forwards non-cache effects to the inner runner", async () => {
-    const runner = withCache(defaultEffectRunner, redisCache(fakeRedis()));
-    const result = await runner({ kind: "cookie", payload: { name: "x" } }, { request: new Request("https://example.com/") });
-    expect(result.ok).toBe(true); // cookie handled by defaultEffectRunner
-  });
-});
-
-describe("postgresSql (SQL adapter)", () => {
-  const fakeSql = (rows: unknown[], rowCount: number): SqlClient & { calls: Array<{ sql: string; params: unknown[] }> } => {
-    const calls: Array<{ sql: string; params: unknown[] }> = [];
-    return {
-      calls,
-      run: async (sql, params) => {
-        calls.push({ sql, params });
-        return { rows, rowCount };
-      }
-    };
-  };
-
-  it("maps mode 'all' to the full row list", async () => {
-    const client = fakeSql([{ id: 1 }, { id: 2 }], 2);
-    const handler = postgresSql(client);
-    const value = await handler({ sql: "SELECT * FROM t WHERE x = ?", params: [42], mode: "all" });
-    expect(value).toEqual([{ id: 1 }, { id: 2 }]);
-    expect(client.calls).toEqual([{ sql: "SELECT * FROM t WHERE x = ?", params: [42] }]);
-  });
-
-  it("maps mode 'first' to the first row (or null)", async () => {
-    expect(await postgresSql(fakeSql([{ id: 1 }], 1))({ sql: "x", params: [], mode: "first" })).toEqual({ id: 1 });
-    expect(await postgresSql(fakeSql([], 0))({ sql: "x", params: [], mode: "first" })).toBeNull();
-  });
-
-  it("maps mode 'run' to { rowsAffected }", async () => {
-    const handler = postgresSql(fakeSql([], 3));
-    const value = await handler({ sql: "DELETE FROM t", params: [], mode: "run" });
-    expect(value).toEqual({ rowsAffected: 3 });
-  });
-});
-
-describe("withQueueProducer + createQueueConsumer (CF Queues)", () => {
-  it("sends an enqueue effect to the configured queue binding", async () => {
-    const sent: unknown[] = [];
-    const runner = withQueueProducer(defaultEffectRunner, { queueBinding: "JOBS" });
-
-    const result = await runner(
-      { kind: "enqueue", payload: { task: "ship", payload: { id: 1 } } },
-      { env: { JOBS: { send: async (m: unknown) => { sent.push(m); } } } }
-    );
-
-    expect(result).toEqual({ ok: true, value: null });
-    expect(sent).toEqual([{ task: "ship", payload: { id: 1 } }]);
-  });
-
-  it("fails clearly when the queue binding is missing", async () => {
-    const runner = withQueueProducer(defaultEffectRunner, { queueBinding: "JOBS" });
-    const result = await runner({ kind: "enqueue", payload: { task: "ship", payload: null } }, { env: {} });
-    expect(result.ok).toBe(false);
-    expect(result.error).toContain("JOBS");
-  });
-
-  it("forwards non-enqueue effects to the inner runner", async () => {
-    const runner = withQueueProducer(defaultEffectRunner);
-    const result = await runner({ kind: "cookie", payload: { name: "x" } }, { request: new Request("https://example.com/", { headers: { cookie: "x=1" } }) });
-    expect(result).toEqual({ ok: true, value: "1" });
-  });
-
-  it("consumer dispatches messages to handlers and acks; retries on missing handler or error", async () => {
-    const calls: Array<{ name: string; payload: unknown }> = [];
-    const acked: string[] = [];
-    const retried: string[] = [];
-
-    const make = (name: string, body: unknown) => ({
-      body,
-      ack: () => acked.push(name),
-      retry: () => retried.push(name)
-    });
-
-    const batch: QueueBatch = {
-      queue: "JOBS",
-      messages: [
-        make("ok", { task: "doThing", payload: { id: 1 } }),
-        make("missing", { task: "noSuchTask", payload: null }),
-        make("boom", { task: "explode", payload: null })
-      ]
-    };
-
-    const consumer = createQueueConsumer({
-      doThing: (payload) => {
-        calls.push({ name: "doThing", payload });
-      },
-      explode: () => {
-        throw new Error("kaboom");
-      }
-    });
-
-    await consumer(batch);
-
-    expect(calls).toEqual([{ name: "doThing", payload: { id: 1 } }]);
-    expect(acked).toEqual(["ok"]);
-    expect(retried.sort()).toEqual(["boom", "missing"]);
-  });
-});

package/test/advanced-robustness.test.ts

@@ -1,75 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { createWorkerApp } from "elm-ssr";
-import { routes, createFlags, exampleEffects } from "../examples/basic/runtime";
-// @ts-expect-error Generated at build time.
-import ElmRuntime from "../generated/examples/basic/app.mjs";
-import { islands, bundleSource } from "../generated/examples/basic/islands-manifest";
-
-const worker = createWorkerApp({
-  elmModule: ElmRuntime,
-  islands,
-  islandsBundle: bundleSource,
-  stylesheet: "",
-  routes,
-  createFlags,
-  effects: exampleEffects
-});
-
-describe("Advanced Robustness: Server Actions", () => {
-  it("handles empty POST body gracefully", async () => {
-    const response = await worker.fetch(new Request("https://example.com/", {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" }
-    }));
-    // Should fall back to the action handler which currently returns 405 for root
-    expect(response.status).toBe(405);
-  });
-
-  it("handles malformed JSON in POST body", async () => {
-    const response = await worker.fetch(new Request("https://example.com/", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: "{ invalid json }"
-    }));
-    expect(response.status).toBe(405); // Still hits the action handler
-  });
-
-  it("ignores unknown Content-Types for form data", async () => {
-    const response = await worker.fetch(new Request("https://example.com/", {
-      method: "POST",
-      headers: { "Content-Type": "text/plain" },
-      body: "just some text"
-    }));
-    expect(response.status).toBe(405);
-  });
-});
-
-describe("Advanced Robustness: Soft Routing API", () => {
-  it("returns 400 for /api/render without a path", async () => {
-    const response = await worker.fetch(new Request("https://example.com/api/render"));
-    const body = await response.json() as { error: string };
-    expect(response.status).toBe(400);
-    expect(body.error).toBe("invalid_path");
-  });
-
-  it("returns 400 for /api/render with relative path", async () => {
-    const response = await worker.fetch(new Request("https://example.com/api/render?path=relative"));
-    expect(response.status).toBe(400);
-  });
-
-  it("handles routes that redirect in the render API", async () => {
-    // We don't have a redirect route in example yet, but we can check the logic
-    // in request-handler.ts: if (rendered.redirect) { return json({ redirect: ... }) }
-  });
-});
-
-describe("Advanced Robustness: Global Event Bus (Worker-side logic)", () => {
-  // Since the bus is client-side, we verify the Worker provides the necessary hooks
-  it("injects the event bus wiring in the islands runtime", async () => {
-    const response = await worker.fetch(new Request("https://example.com/__elm-ssr/islands.js"));
-    const source = await response.text();
-    expect(source).toContain("elm-ssr-broadcast");
-    expect(source).toContain("window.dispatchEvent");
-    expect(source).toContain("window.addEventListener");
-  });
-});