elm-ssr 0.1.0

package/src/backends.ts

@@ -0,0 +1,116 @@
+import type { EffectRunner, SqlQuery } from "./effects";
+
+// === Cache (KV / Redis / …) ===
+
+/**
+ * A driver-agnostic cache backend. Stores arbitrary JSON-serialisable values
+ * with an optional TTL in seconds. Returns `null` on a miss.
+ */
+export interface CacheBackend {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+}
+
+/**
+ * Wrap an effect runner so `cacheGet`/`cachePut` are served by `backend`. All
+ * other effects pass through to the wrapped runner unchanged. Compose with
+ * `withTasks`, `withQueueProducer`, etc.:
+ *
+ *     withTasks(
+ *       withCache(inMemoryEffects({ sql: postgresSql(pg) }), redisCache(redis)),
+ *       { sendEmail }
+ *     )
+ */
+export const withCache = (runner: EffectRunner, backend: CacheBackend): EffectRunner =>
+  async (effect, context) => {
+    if (effect.kind === "cacheGet") {
+      const value = await backend.get(String(effect.payload.key));
+      return { ok: true, value: value ?? null };
+    }
+
+    if (effect.kind === "cachePut") {
+      const ttl = typeof effect.payload.ttlSeconds === "number" ? effect.payload.ttlSeconds : undefined;
+      await backend.put(String(effect.payload.key), effect.payload.value ?? null, ttl);
+      return { ok: true, value: null };
+    }
+
+    return runner(effect, context);
+  };
+
+/**
+ * Minimal Redis-like client interface — values are strings; the adapter handles
+ * JSON encoding/decoding. Wire any matching client:
+ *
+ *     // Bun built-in:
+ *     redisCache({
+ *       get: (k) => Bun.redis.get(k),
+ *       set: (k, v, ttl) => ttl !== undefined ? Bun.redis.set(k, v, "EX", ttl) : Bun.redis.set(k, v)
+ *     })
+ *
+ *     // ioredis:
+ *     redisCache({
+ *       get: (k) => ioredis.get(k),
+ *       set: (k, v, ttl) => ttl !== undefined ? ioredis.set(k, v, "EX", ttl) : ioredis.set(k, v)
+ *     })
+ */
+export interface CacheClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds?: number): Promise<unknown>;
+}
+
+/** A `CacheBackend` backed by a Redis-like client. JSON-encodes values on store. */
+export const redisCache = (client: CacheClient): CacheBackend => ({
+  get: async (key) => {
+    const raw = await client.get(key);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  },
+  put: async (key, value, ttlSeconds) => {
+    await client.set(key, JSON.stringify(value), ttlSeconds);
+  }
+});
+
+// === SQL (D1 / Postgres / SQLite / …) ===
+
+/**
+ * Minimal SQL client interface. Wire any driver:
+ *
+ *     // Bun built-in (Bun.sql):
+ *     postgresSql({
+ *       run: async (q, p) => {
+ *         const rows = await Bun.sql.unsafe(q, p);
+ *         return { rows: [...rows], rowCount: (rows as { count?: number }).count ?? rows.length };
+ *       }
+ *     })
+ *
+ *     // node-postgres:
+ *     postgresSql({
+ *       run: (q, p) => pool.query(q, p).then((r) => ({ rows: r.rows, rowCount: r.rowCount ?? 0 }))
+ *     })
+ */
+export interface SqlClient {
+  run(sql: string, params: unknown[]): Promise<{ rows: unknown[]; rowCount: number }>;
+}
+
+/**
+ * A SqlQuery handler (use as `inMemoryEffects({ sql: postgresSql(client) })`)
+ * backed by any client matching `SqlClient`. Maps `query`/`queryOne`/`execute`
+ * to the client's single `run` method.
+ */
+export const postgresSql = (client: SqlClient) =>
+  async ({ sql, params, mode }: SqlQuery): Promise<unknown> => {
+    const { rows, rowCount } = await client.run(sql, params);
+    if (mode === "first") {
+      return rows[0] ?? null;
+    }
+    if (mode === "run") {
+      return { rowsAffected: rowCount };
+    }
+    return rows;
+  };

package/src/client-runtime/islands.ts

@@ -0,0 +1,247 @@
+import type { IslandMetadata } from "../app";
+
+// The island client runtime, as a source string shipped to the browser. The
+// core is factored into `createIslandsRuntime(deps)` so it can be exercised in
+// tests against a real DOM with an injected Elm bundle; the browser tail just
+// wires real globals and kicks it off.
+export const islandsCoreSource = `
+function lookupModule(elm, moduleName) {
+  return moduleName.split(".").reduce((current, part) => (current ? current[part] : undefined), elm);
+}
+
+function createIslandsRuntime(deps) {
+  const document = deps.document;
+  const window = deps.window;
+  const manifest = deps.manifest;
+  const loadBundle = deps.loadBundle;
+
+  const persistentIslands = new Map(); // id -> live marker element (kept across navigations)
+  const cleanups = new Map();          // marker element -> () => void (remove its bus listener)
+
+  const wireBus = (app, marker) => {
+    if (!app || !app.ports) {
+      return;
+    }
+
+    if (app.ports.broadcastOut) {
+      app.ports.broadcastOut.subscribe((event) => {
+        window.dispatchEvent(new window.CustomEvent("elm-ssr-broadcast", { detail: event }));
+      });
+    }
+
+    if (app.ports.broadcastIn) {
+      const handler = (event) => app.ports.broadcastIn.send(event.detail);
+      window.addEventListener("elm-ssr-broadcast", handler);
+      cleanups.set(marker, () => window.removeEventListener("elm-ssr-broadcast", handler));
+    }
+  };
+
+  const bootMarker = (ElmModule, marker) => {
+    const id = marker.getAttribute("data-elmssr-id");
+
+    // A live persistent instance already exists: move it into this marker's
+    // place instead of mounting a fresh one, preserving its state.
+    if (id && persistentIslands.has(id)) {
+      const live = persistentIslands.get(id);
+      if (live !== marker) {
+        marker.replaceWith(live);
+      }
+      return;
+    }
+
+    const name = marker.getAttribute("data-elmssr-island");
+    const entry = name ? manifest[name] : undefined;
+
+    if (!entry) {
+      throw new Error("Unknown island: " + name);
+    }
+
+    const islandModule = lookupModule(ElmModule, entry.module);
+
+    if (!islandModule || typeof islandModule.init !== "function") {
+      throw new Error("Elm island module did not expose init(): " + entry.module);
+    }
+
+    const flags = JSON.parse(marker.getAttribute("data-elmssr-props") || "{}");
+
+    // Browser.element replaces the node it mounts into, so mount into a child:
+    // the <elm-ssr-island> marker stays in the DOM and is the persistent unit.
+    while (marker.firstChild) {
+      marker.removeChild(marker.firstChild);
+    }
+
+    const mount = document.createElement("div");
+    marker.appendChild(mount);
+
+    const app = islandModule.init({ node: mount, flags });
+    marker.setAttribute("data-elmssr-booted", "true");
+
+    if (id) {
+      persistentIslands.set(id, marker);
+    }
+
+    wireBus(app, marker);
+  };
+
+  const findMarkers = (root) => Array.prototype.slice.call(root.getElementsByTagName("elm-ssr-island"));
+
+  const bootIslands = async () => {
+    const markers = findMarkers(document);
+
+    if (markers.length === 0) {
+      return;
+    }
+
+    const ElmModule = await loadBundle();
+
+    for (const marker of markers) {
+      if (marker.getAttribute("data-elmssr-booted")) {
+        continue;
+      }
+
+      try {
+        bootMarker(ElmModule, marker);
+      } catch (error) {
+        console.error("elm-ssr: failed to boot island", marker.getAttribute("data-elmssr-island"), error);
+      }
+    }
+  };
+
+  // Tear down islands that are about to be removed. Persistent islands are kept
+  // alive (their refs live in persistentIslands and transfer to the next page),
+  // so only non-persistent ones are cleaned up. Elm has no program shutdown, so
+  // the controllable leak is the global bus listener — remove it here.
+  const cleanupRemovedIslands = (container) => {
+    for (const marker of findMarkers(container)) {
+      const id = marker.getAttribute("data-elmssr-id");
+
+      if (id && persistentIslands.get(id) === marker) {
+        continue;
+      }
+
+      const cleanup = cleanups.get(marker);
+
+      if (cleanup) {
+        cleanup();
+        cleanups.delete(marker);
+      }
+    }
+  };
+
+  const managedHeadNodes = (head) => {
+    const metas = Array.prototype.slice.call(head.getElementsByTagName("meta"));
+    const links = Array.prototype.slice
+      .call(head.getElementsByTagName("link"))
+      .filter((link) => link.getAttribute("rel") === "stylesheet");
+    return metas.concat(links);
+  };
+
+  const syncHead = (sourceDoc) => {
+    document.title = sourceDoc.title;
+
+    for (const node of managedHeadNodes(document.head)) {
+      node.remove();
+    }
+
+    for (const node of managedHeadNodes(sourceDoc.head)) {
+      const copy = document.createElement(node.tagName);
+      for (const name of node.getAttributeNames()) {
+        copy.setAttribute(name, node.getAttribute(name));
+      }
+      document.head.appendChild(copy);
+    }
+  };
+
+  const navigate = async (url, push = true) => {
+    try {
+      const response = await window.fetch("/api/render?path=" + encodeURIComponent(url.pathname + url.search));
+      const result = await response.json();
+
+      if (result.redirect) {
+        window.location.href = result.redirect;
+        return;
+      }
+
+      if (!result.html) {
+        return;
+      }
+
+      const incoming = new window.DOMParser().parseFromString(result.html, "text/html");
+      const newRoot = incoming.getElementById("elm-ssr-root");
+      const currentRoot = document.getElementById("elm-ssr-root");
+
+      if (!newRoot || !currentRoot) {
+        return;
+      }
+
+      syncHead(incoming);
+      cleanupRemovedIslands(currentRoot);
+      currentRoot.innerHTML = newRoot.innerHTML;
+
+      if (push) {
+        window.history.pushState({}, "", url.href);
+      }
+
+      await bootIslands();
+    } catch (error) {
+      console.error("elm-ssr: navigation failed", error);
+      window.location.href = url.href;
+    }
+  };
+
+  const handleLinkClick = (event) => {
+    const target = event.target;
+    let link = target && target.nodeType === 1 ? target : target ? target.parentElement : null;
+
+    while (link && link.tagName !== "A") {
+      link = link.parentElement;
+    }
+
+    if (!link) {
+      return;
+    }
+
+    if (link.getAttribute("target") === "_blank" || link.getAttribute("download") !== null) {
+      return;
+    }
+
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+      return;
+    }
+
+    const url = new URL(link.href);
+
+    if (url.origin !== window.location.origin) {
+      return;
+    }
+
+    // Same page (hash-only / in-page anchor): let the browser handle it.
+    if (url.pathname === window.location.pathname && url.search === window.location.search) {
+      return;
+    }
+
+    event.preventDefault();
+    navigate(url);
+  };
+
+  return { bootIslands, navigate, handleLinkClick, persistentIslands, cleanups };
+}
+`;
+
+const encodeManifest = (islands: Record<string, IslandMetadata>): string => JSON.stringify(islands);
+
+export const createIslandsRuntimeSource = (islands: Record<string, IslandMetadata>): string => `
+${islandsCoreSource}
+
+const runtime = createIslandsRuntime({
+  document,
+  window,
+  manifest: ${encodeManifest(islands)},
+  loadBundle: () => import("/__elm-ssr/islands-bundle.js").then((module) => module.default)
+});
+
+window.addEventListener("click", runtime.handleLinkClick);
+window.addEventListener("popstate", () => runtime.navigate(new URL(window.location.href), false));
+
+runtime.bootIslands();
+`;

package/src/effects.ts

@@ -0,0 +1,267 @@
+import { parse as parseCookieHeader } from "cookie";
+
+export interface LoaderEffect {
+  kind: string;
+  payload: Record<string, unknown>;
+}
+
+export interface LoaderEffectResult {
+  ok: boolean;
+  value?: unknown;
+  error?: string;
+}
+
+/** Per-request context handed to the effect runner (e.g. Cloudflare bindings). */
+export interface EffectContext {
+  env?: Record<string, unknown>;
+  request?: Request;
+  /** Keeps the runtime alive for background work scheduled after the response. */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+/**
+ * Runs a single side effect requested by an Elm loader or action. This is the
+ * only place a loader's IO actually happens — the Elm side just describes what
+ * it needs, with backend-neutral kinds (`cacheGet`, `query`, …) so the same app
+ * runs on Cloudflare (KV/D1) or locally (Redis/SQLite) by swapping the adapter.
+ */
+export type EffectRunner = (effect: LoaderEffect, context: EffectContext) => Promise<LoaderEffectResult>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+export const normalizeEffect = (value: unknown): LoaderEffect => {
+  if (isRecord(value) && typeof value.kind === "string") {
+    return {
+      kind: value.kind,
+      payload: isRecord(value.payload) ? value.payload : {}
+    };
+  }
+
+  return { kind: "unknown", payload: {} };
+};
+
+const cookieEffect = (effect: LoaderEffect, context: EffectContext): LoaderEffectResult => {
+  const header = context.request?.headers.get("cookie") ?? "";
+  const cookies = header ? parseCookieHeader(header) : {};
+  const name = String(effect.payload.name);
+  const value = cookies[name];
+  return { ok: true, value: typeof value === "string" ? value : null };
+};
+
+const fetchJsonEffect = async (effect: LoaderEffect): Promise<LoaderEffectResult> => {
+  const url = typeof effect.payload.url === "string" ? effect.payload.url : "";
+
+  try {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      return { ok: false, error: `fetchJson received ${response.status} from ${url}` };
+    }
+
+    return { ok: true, value: await response.json() };
+  } catch (error) {
+    return { ok: false, error: `fetchJson failed for ${url}: ${String(error)}` };
+  }
+};
+
+/**
+ * The fallback runner: `fetchJson` works everywhere, but backend effects report
+ * that no adapter is configured rather than silently succeeding.
+ */
+export const defaultEffectRunner: EffectRunner = async (effect, context) => {
+  if (effect.kind === "fetchJson") {
+    return fetchJsonEffect(effect);
+  }
+
+  if (effect.kind === "cookie") {
+    return cookieEffect(effect, context);
+  }
+
+  return {
+    ok: false,
+    error: `Effect "${effect.kind}" has no configured backend. Pass an adapter (cloudflareEffects or inMemoryEffects) as \`effects\`.`
+  };
+};
+
+// Minimal shapes of the Cloudflare bindings we use, to avoid a types dependency.
+interface KVNamespaceLike {
+  get(key: string, type: "json"): Promise<unknown>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+interface D1ResultLike {
+  results?: unknown[];
+  meta?: { changes?: number };
+}
+
+interface D1StatementLike {
+  bind(...values: unknown[]): D1StatementLike;
+  all(): Promise<D1ResultLike>;
+  first(): Promise<unknown>;
+  run(): Promise<D1ResultLike>;
+}
+
+interface D1DatabaseLike {
+  prepare(sql: string): D1StatementLike;
+}
+
+export interface CloudflareEffectsConfig {
+  /** KV binding used for `cacheGet`/`cachePut`. Default `"CACHE"`. */
+  cacheBinding?: string;
+  /** D1 binding used for `query`/`queryOne`/`execute`. Default `"DB"`. */
+  dbBinding?: string;
+}
+
+const sqlParams = (effect: LoaderEffect): unknown[] =>
+  Array.isArray(effect.payload.params) ? effect.payload.params : [];
+
+/** Cloudflare adapter: maps neutral effects to KV, D1, and env bindings. */
+export const cloudflareEffects = (config: CloudflareEffectsConfig = {}): EffectRunner => {
+  const cacheBinding = config.cacheBinding ?? "CACHE";
+  const dbBinding = config.dbBinding ?? "DB";
+
+  return async (effect, context) => {
+    const env = context.env ?? {};
+
+    switch (effect.kind) {
+      case "fetchJson":
+        return fetchJsonEffect(effect);
+
+      case "cacheGet": {
+        const kv = env[cacheBinding] as KVNamespaceLike | undefined;
+        if (!kv) {
+          return { ok: false, error: `Missing KV binding "${cacheBinding}"` };
+        }
+        const value = await kv.get(String(effect.payload.key), "json");
+        return { ok: true, value: value ?? null };
+      }
+
+      case "cachePut": {
+        const kv = env[cacheBinding] as KVNamespaceLike | undefined;
+        if (!kv) {
+          return { ok: false, error: `Missing KV binding "${cacheBinding}"` };
+        }
+        const ttl = typeof effect.payload.ttlSeconds === "number" ? { expirationTtl: effect.payload.ttlSeconds } : undefined;
+        await kv.put(String(effect.payload.key), JSON.stringify(effect.payload.value ?? null), ttl);
+        return { ok: true, value: null };
+      }
+
+      case "query":
+      case "queryOne":
+      case "execute": {
+        const db = env[dbBinding] as D1DatabaseLike | undefined;
+        if (!db) {
+          return { ok: false, error: `Missing D1 binding "${dbBinding}"` };
+        }
+        const statement = db.prepare(String(effect.payload.sql)).bind(...sqlParams(effect));
+        if (effect.kind === "query") {
+          const result = await statement.all();
+          return { ok: true, value: result.results ?? [] };
+        }
+        if (effect.kind === "queryOne") {
+          const row = await statement.first();
+          return { ok: true, value: row ?? null };
+        }
+        const result = await statement.run();
+        return { ok: true, value: { rowsAffected: result.meta?.changes ?? 0 } };
+      }
+
+      case "env": {
+        const value = env[String(effect.payload.name)];
+        return { ok: true, value: typeof value === "string" ? value : null };
+      }
+
+      case "cookie":
+        return cookieEffect(effect, context);
+
+      default:
+        return { ok: false, error: `Unknown effect: ${effect.kind}` };
+    }
+  };
+};
+
+export interface SqlQuery {
+  sql: string;
+  params: unknown[];
+  mode: "all" | "first" | "run";
+}
+
+export interface InMemoryEffectsOptions {
+  /** Values returned by the `env` effect. */
+  env?: Record<string, string>;
+  /** Backing store for the cache; pass one in to share/inspect it. */
+  cache?: Map<string, { value: unknown; expiresAt?: number }>;
+  /** SQL backend, e.g. a bun:sqlite or Postgres handler. Required for query/execute. */
+  sql?: (query: SqlQuery) => unknown | Promise<unknown>;
+  /** Override `fetchJson` (e.g. fixtures in tests); defaults to a real fetch. */
+  fetchJson?: (url: string) => unknown | Promise<unknown>;
+  now?: () => number;
+}
+
+/** Local/test adapter: in-memory cache + env, with a pluggable SQL backend. */
+export const inMemoryEffects = (options: InMemoryEffectsOptions = {}): EffectRunner => {
+  const cache = options.cache ?? new Map<string, { value: unknown; expiresAt?: number }>();
+  const env = options.env ?? {};
+  const now = options.now ?? (() => Date.now());
+
+  return async (effect, context) => {
+    switch (effect.kind) {
+      case "fetchJson": {
+        if (options.fetchJson) {
+          try {
+            return { ok: true, value: await options.fetchJson(String(effect.payload.url)) };
+          } catch (error) {
+            return { ok: false, error: String(error) };
+          }
+        }
+        return fetchJsonEffect(effect);
+      }
+
+      case "cacheGet": {
+        const entry = cache.get(String(effect.payload.key));
+        if (!entry) {
+          return { ok: true, value: null };
+        }
+        if (entry.expiresAt !== undefined && entry.expiresAt <= now()) {
+          cache.delete(String(effect.payload.key));
+          return { ok: true, value: null };
+        }
+        return { ok: true, value: entry.value };
+      }
+
+      case "cachePut": {
+        const ttl = typeof effect.payload.ttlSeconds === "number" ? effect.payload.ttlSeconds : undefined;
+        cache.set(String(effect.payload.key), {
+          value: effect.payload.value ?? null,
+          expiresAt: ttl !== undefined ? now() + ttl * 1000 : undefined
+        });
+        return { ok: true, value: null };
+      }
+
+      case "query":
+      case "queryOne":
+      case "execute": {
+        if (!options.sql) {
+          return { ok: false, error: 'The "sql" handler is not configured in inMemoryEffects.' };
+        }
+        const mode = effect.kind === "query" ? "all" : effect.kind === "queryOne" ? "first" : "run";
+        try {
+          const value = await options.sql({ sql: String(effect.payload.sql), params: sqlParams(effect), mode });
+          return { ok: true, value };
+        } catch (error) {
+          return { ok: false, error: String(error) };
+        }
+      }
+
+      case "env": {
+        const value = env[String(effect.payload.name)];
+        return { ok: true, value: typeof value === "string" ? value : null };
+      }
+
+      default:
+        return defaultEffectRunner(effect, context);
+    }
+  };
+};