@nifrajs/web 0.1.0-alpha.1

package/src/prerender.ts

@@ -0,0 +1,209 @@
+/**
+ * Build-time SSG driver. Prerendering is framework-agnostic by construction: a nifra SSR page is
+ * "just `app.fetch(GET)` returning a streamed `Response`", so prerendering = drive that same handler
+ * at build with a synthetic request, drain the body to bytes, and write the HTML to disk. No adapter
+ * (React/Solid/Vue/Preact/Svelte) is touched — this sits entirely above the render seam.
+ *
+ * Handles **static** routes (opt in via `export const prerender = true`) and **dynamic** `:param`
+ * routes (enumerate concrete params via `export const getStaticPaths`). Catch-all/wildcard (`*`)
+ * routes are not supported.
+ */
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, resolve, sep } from "node:path"
+import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
+import { DATA_HEADER } from "./router.ts"
+
+/** Minimal app surface the driver needs — just a fetch handler (a built `createWebApp`). */
+export interface PrerenderApp {
+  fetch(req: Request): Response | Promise<Response>
+}
+
+export interface PrerenderOptions {
+  /** The built web app (a `createWebApp` result). A synthetic `GET <origin><pattern>` is issued per
+   * prerenderable route; its drained response body is written to disk. */
+  readonly app: PrerenderApp
+  /** The route manifest's `routes`. Only **static** routes whose module exports `prerender === true`
+   * are emitted; everything else is recorded in {@link PrerenderResult.skipped} with a reason. */
+  readonly routes: readonly RouteEntry[]
+  /** Absolute output directory. `<pattern>/index.html` is written under it (`/` → `index.html`). */
+  readonly outDir: string
+  /** Origin for the synthetic request URL. Default `http://localhost`. Only the path is meaningful;
+   * loaders see this as `request.url`, so set it if a loader builds absolute URLs from the origin. */
+  readonly origin?: string
+}
+
+export interface PrerenderEntry {
+  /** The route pattern that was prerendered (e.g. `/`, `/about`). */
+  readonly path: string
+  /** The written file, relative to `outDir` (e.g. `index.html`, `about/index.html`). */
+  readonly file: string
+  /** Byte length of the written HTML. */
+  readonly bytes: number
+  /** The loader-data file written alongside (`<path>/_data.json`) so a client soft-nav INTO this
+   * route skips the worker. Absent when the data-mode response is NDJSON (a deferred loader). */
+  readonly dataFile?: string
+}
+
+export interface PrerenderResult {
+  readonly prerendered: readonly PrerenderEntry[]
+  readonly skipped: readonly { readonly path: string; readonly reason: string }[]
+  /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default) — so the deploy
+   * layer knows whether unlisted paths should hit the worker (`"ssr"`) or 404 (`"404"`). */
+  readonly fallbacks: Readonly<Record<string, "ssr" | "404">>
+}
+
+/** Map a route path to its output file: `/` → `index.html`, `/a/b` → `a/b/index.html`. */
+export function htmlFileFor(pattern: string): string {
+  const trimmed = pattern.replace(/^\/+/, "").replace(/\/+$/, "")
+  return trimmed === "" ? "index.html" : `${trimmed}/index.html`
+}
+
+/** The static loader-data file next to a route's `index.html`: `/` → `_data.json`, `/a/b` →
+ * `a/b/_data.json`. The client fetches it on soft-nav into a prerendered route (no worker). */
+export function dataFileFor(pattern: string): string {
+  return htmlFileFor(pattern).replace(/index\.html$/, "_data.json")
+}
+
+const outputPath = (root: string, file: string): string | undefined => {
+  const abs = resolve(root, file)
+  return abs !== root && abs.startsWith(`${root}${sep}`) ? abs : undefined
+}
+
+/**
+ * Render every opted-in static route to a static `index.html` under `outDir`. Run AFTER `buildClient`
+ * (so the app references the hashed client entry). Returns a report of what was emitted vs skipped —
+ * the caller can use `prerendered` to wire a hybrid deploy (e.g. exclude those paths from the SSR
+ * worker so the CDN serves the static file). Never throws on a per-route miss: a non-OK response or a
+ * non-opted/dynamic route is recorded in `skipped` and the build continues.
+ */
+export async function prerenderRoutes(options: PrerenderOptions): Promise<PrerenderResult> {
+  const origin = options.origin ?? "http://localhost"
+  const prerendered: PrerenderEntry[] = []
+  const skipped: { path: string; reason: string }[] = []
+  const fallbacks: Record<string, "ssr" | "404"> = {}
+  const outRoot = resolve(options.outDir)
+
+  // Render one concrete path → drain the streamed document to bytes → write its index.html. Shared by
+  // static (one path) and dynamic (one path per getStaticPaths entry) routes; never throws.
+  const renderPath = async (path: string): Promise<void> => {
+    const res = await options.app.fetch(new Request(`${origin}${path}`))
+    if (!res.ok) {
+      // A failed render is a per-route skip, not a build failure — surfaced for the caller to log.
+      skipped.push({ path, reason: `render returned HTTP ${res.status}` })
+      return
+    }
+    const html = await res.text()
+    const file = htmlFileFor(path)
+    const abs = outputPath(outRoot, file)
+    if (abs === undefined) {
+      skipped.push({ path, reason: "unsafe output path" })
+      return
+    }
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, html)
+
+    // Also emit the loader data as a static `_data.json` next to it, so a client soft-nav into this
+    // route fetches a file instead of hitting the worker. Only when the data-mode response is plain
+    // JSON — a deferred loader answers with NDJSON, which the static fast-path doesn't cover (the
+    // client falls back to the worker for those).
+    let dataFile: string | undefined
+    const dataRes = await options.app.fetch(
+      new Request(`${origin}${path}`, { headers: { [DATA_HEADER]: "1" } }),
+    )
+    if (
+      dataRes.ok &&
+      !(dataRes.headers.get("content-type") ?? "").includes("application/x-ndjson")
+    ) {
+      dataFile = dataFileFor(path)
+      const dataAbs = outputPath(outRoot, dataFile)
+      if (dataAbs === undefined) {
+        await dataRes.body?.cancel()
+        dataFile = undefined
+      } else {
+        writeFileSync(dataAbs, await dataRes.text())
+      }
+    } else {
+      await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) — release the stream
+    }
+
+    prerendered.push({ path, file, bytes: html.length, ...(dataFile ? { dataFile } : {}) })
+  }
+
+  for (const route of options.routes) {
+    if (route.pattern.includes("*")) {
+      skipped.push({ path: route.pattern, reason: "catch-all/wildcard route — not supported" })
+      continue
+    }
+    const mod = await route.load()
+
+    if (route.pattern.includes(":")) {
+      // Dynamic route → enumerate concrete paths via `getStaticPaths`.
+      if (mod.getStaticPaths === undefined) {
+        skipped.push({ path: route.pattern, reason: "dynamic route without getStaticPaths" })
+        continue
+      }
+      const { paths, fallback = "ssr" } = await mod.getStaticPaths()
+      fallbacks[route.pattern] = fallback
+      for (const { params } of paths) {
+        const { path, missing } = fillRoutePattern(route.pattern, params)
+        if (missing.length > 0) {
+          skipped.push({
+            path: route.pattern,
+            reason: `getStaticPaths missing param(s): ${missing.join(", ")}`,
+          })
+          continue
+        }
+        await renderPath(path)
+      }
+      continue
+    }
+
+    // Static route → opt-in flag.
+    if (mod.prerender !== true) {
+      skipped.push({
+        path: route.pattern,
+        reason: "not opted in (`export const prerender = true`)",
+      })
+      continue
+    }
+    await renderPath(route.pattern)
+  }
+
+  return { prerendered, skipped, fallbacks }
+}
+
+/** A Cloudflare Pages `_routes.json` document. `exclude`d paths are served straight from the CDN (the
+ * Function/worker is NOT invoked); everything else in `include` hits the worker. */
+export interface CloudflarePagesRoutes {
+  readonly version: 1
+  readonly include: readonly string[]
+  readonly exclude: readonly string[]
+}
+
+export interface CloudflarePagesRoutesOptions {
+  /** Prerendered request paths (e.g. `prerenderRoutes(...).prerendered.map(p => p.path)`, or the
+   * build's `prerendered.json`). Each is excluded from the worker — plus its static `_data.json`. */
+  readonly prerendered: readonly string[]
+  /** Extra globs to keep OFF the worker (CDN-served). Default `["/assets/*"]` (the hashed bundle). */
+  readonly staticGlobs?: readonly string[]
+}
+
+/**
+ * Build a Cloudflare Pages `_routes.json` for a HYBRID SSG deploy: the prerendered HTML + their static
+ * `_data.json` + the asset bundle are `exclude`d (CDN serves them directly), and everything else falls
+ * through to the SSR `_worker.js`. Write the result to `dist/_routes.json`.
+ *
+ * ⚠️ Cloudflare caps `_routes.json` at **100** include+exclude rules total, and each prerendered path
+ * costs 2 (the doc + its `_data.json`). For a large SSG site, exclude by **prefix glob** (e.g.
+ * `/blog/*`) instead of listing every path — pass those via `staticGlobs` and a smaller `prerendered`.
+ */
+export function cloudflarePagesRoutes(
+  options: CloudflarePagesRoutesOptions,
+): CloudflarePagesRoutes {
+  const exclude = [...(options.staticGlobs ?? ["/assets/*"])]
+  for (const path of options.prerendered) {
+    exclude.push(path) // the prerendered document
+    exclude.push(path === "/" ? "/_data.json" : `${path.replace(/\/+$/, "")}/_data.json`) // its data
+  }
+  return { version: 1, include: ["/*"], exclude }
+}

package/src/query.ts

@@ -0,0 +1,250 @@
+/**
+ * The agnostic keyed query-cache — a `query(key, fn)` primitive with in-flight dedup, `staleTime`
+ * freshness, prefix `invalidateQueries`, and bounded GC. Pure logic, no `window`, no framework, no
+ * `Date.now`/timers (the clock is injected) — so it unit-tests deterministically and is safe to import
+ * from the SSR core's main entry. A per-adapter binding (`useQuery`/`createQuery`) subscribes to a
+ * query's `subscribe`/`snapshot` store (the same shape the router + fetchers use).
+ *
+ * This is a SECOND keyed cache, distinct from the router's path-keyed route cache (F16): route loaders
+ * + navigation use the path cache; component-level interactive data (search, infinite scroll, polling)
+ * uses this arbitrary-keyed query cache. The two coexist.
+ */
+
+/** A query's lifecycle status. `pending` = no data yet; `success`/`error` once it has settled once. */
+export type QueryStatus = "pending" | "success" | "error"
+
+/** A query's observable state — what a binding renders. A new (frozen) object per transition, so a
+ * `useSyncExternalStore`/signal binding can compare by reference. */
+export interface QueryState<T = unknown> {
+  readonly status: QueryStatus
+  readonly data: T | undefined
+  readonly error: unknown
+  /** True while a fetch is in flight — the initial load OR a background refetch (data may still show). */
+  readonly isFetching: boolean
+  /** When `data` was last set (via the injected clock); drives `staleTime`. `-Infinity` until first set. */
+  readonly updatedAt: number
+}
+
+/** A stable per-key handle: subscribe to its state, read a snapshot, trigger a fetch/refetch. */
+export interface QueryHandle<T = unknown> {
+  snapshot: () => QueryState<T>
+  subscribe: (listener: () => void) => () => void
+  /** Fetch when stale or absent (fresh ⇒ no-op); joins an in-flight fetch (dedup). Resolves to the
+   * data, or rejects if the fetch threw. */
+  fetch: () => Promise<T>
+  /** Refetch regardless of staleness (still joins an in-flight fetch). */
+  refetch: () => Promise<T>
+}
+
+export interface QueryClientOptions {
+  /** Monotonic clock in ms — injected so the core stays deterministic + testable; the adapter binding
+   * passes `() => Date.now()`. */
+  readonly now: () => number
+  /** Data stays fresh this long after a fetch; older ⇒ refetch on the next `fetch()` (default `0`). */
+  readonly staleTime?: number
+  /** Evict an entry this long (ms) after its last subscriber leaves (default 5 min). */
+  readonly gcTime?: number
+  /** Hard cap on cached entries — LRU-evict the oldest *unsubscribed* entry past it (default 1000). */
+  readonly max?: number
+}
+
+/** The keyed query cache. One per app (a binding registers it like the router). */
+export interface QueryClient {
+  /** Get the stable {@link QueryHandle} for `key`, fetched via `fn`. Re-binds the latest `fn` each
+   * call (closures change between renders); returns the same handle for the same (hashed) key. */
+  query: <T>(key: unknown, fn: () => Promise<T>) => QueryHandle<T>
+  /** Mark matching cached queries stale and refetch the **mounted** ones (subscribers > 0). Array
+   * keys match by **prefix** (`["todo"]` ⇒ every `["todo", …]`); other keys match exactly. */
+  invalidateQueries: (keyOrPrefix: unknown) => void
+}
+
+/**
+ * Hash a query key to a stable cache string. Object keys are sorted (so `{a,b}` ≡ `{b,a}`); arrays
+ * keep order. Keys must be serializable — a function/symbol in the key throws (it can't be a stable
+ * identity). Mirrors TanStack Query's structural hashing.
+ */
+export function hashQueryKey(key: unknown): string {
+  return JSON.stringify(key, (_k, value) => {
+    if (typeof value === "function" || typeof value === "symbol")
+      throw new TypeError("[nifra/web] a query key must be serializable (no functions/symbols)")
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const obj = value as Record<string, unknown>
+      return Object.fromEntries(
+        Object.keys(obj)
+          .sort()
+          .map((k) => [k, obj[k]]),
+      )
+    }
+    return value
+  })
+}
+
+// Structural array-prefix match on un-hashed keys: invalidate(["todo"]) hits ["todo", id]. Non-array
+// keys (or a non-array prefix) match exactly (by hash).
+function keyMatchesPrefix(key: unknown, prefix: unknown): boolean {
+  if (!Array.isArray(key) || !Array.isArray(prefix))
+    return hashQueryKey(key) === hashQueryKey(prefix)
+  return (
+    prefix.length <= key.length && prefix.every((p, i) => hashQueryKey(key[i]) === hashQueryKey(p))
+  )
+}
+
+interface Entry {
+  readonly key: unknown
+  fn: () => Promise<unknown>
+  state: QueryState
+  promise: Promise<unknown> | undefined
+  /** The {@link generation} the in-flight {@link promise} started at — so a fetch begun *before* an
+   * `invalidateQueries` (which bumps `generation`) is recognized as superseded, not joined. */
+  promiseGen: number
+  /** Bumped by `invalidateQueries`/`refetch` to supersede any in-flight fetch begun before it. */
+  generation: number
+  invalidated: boolean
+  subscribers: number
+  /** Scheduled eviction time (set when subscribers hit 0; cleared on resubscribe). */
+  gcAt: number | undefined
+  readonly listeners: Set<() => void>
+  // Assigned once just after construction (the handle's closures reference this entry); not readonly.
+  handle: QueryHandle
+}
+
+const PENDING: QueryState = Object.freeze({
+  status: "pending",
+  data: undefined,
+  error: undefined,
+  isFetching: false,
+  updatedAt: Number.NEGATIVE_INFINITY,
+})
+
+export function createQueryClient(options: QueryClientOptions): QueryClient {
+  const { now } = options
+  const staleTime = options.staleTime ?? 0
+  const gcTime = options.gcTime ?? 5 * 60_000
+  const max = options.max ?? 1000
+  const cache = new Map<string, Entry>()
+
+  // Lazily evict entries whose GC timer has elapsed (no subscribers), then enforce the hard cap by
+  // dropping the oldest-inserted unsubscribed entries. Called on every `query()` — no background timer.
+  const sweep = (): void => {
+    const t = now()
+    for (const [h, e] of cache) {
+      if (e.subscribers === 0 && e.gcAt !== undefined && t >= e.gcAt) cache.delete(h)
+    }
+    if (cache.size <= max) return
+    for (const [h, e] of cache) {
+      if (cache.size <= max) break
+      if (e.subscribers === 0) cache.delete(h) // oldest-inserted unsubscribed first (Map order)
+    }
+  }
+
+  const query = <T>(key: unknown, fn: () => Promise<T>): QueryHandle<T> => {
+    sweep()
+    const h = hashQueryKey(key)
+    const existing = cache.get(h)
+    if (existing !== undefined) {
+      existing.fn = fn as () => Promise<unknown> // re-bind the latest closure
+      return existing.handle as QueryHandle<T>
+    }
+    const entry: Entry = {
+      key,
+      fn: fn as () => Promise<unknown>,
+      state: PENDING,
+      promise: undefined,
+      promiseGen: 0,
+      generation: 0,
+      invalidated: false,
+      subscribers: 0,
+      gcAt: undefined,
+      listeners: new Set(),
+      // `handle` is assigned just below; the cast lets the entry reference itself.
+      handle: undefined as unknown as QueryHandle,
+    }
+    const emit = (): void => {
+      // Iterate the live set — no per-emit copy (the common case is 0–1 subscribers; the spread
+      // allocated an array on every state transition ∝ subscriber count). Contract: a listener must
+      // not synchronously subscribe/unsubscribe during notification — `useSyncExternalStore`/signal/
+      // store bindings don't (un/subscribe happens in a later effect/cleanup tick).
+      if (entry.listeners.size === 0) return
+      for (const l of entry.listeners) l()
+    }
+    const setState = (next: QueryState): void => {
+      entry.state = Object.freeze(next)
+      emit()
+    }
+    const isStale = (): boolean => entry.invalidated || now() - entry.state.updatedAt >= staleTime
+
+    const run = (force: boolean): Promise<unknown> => {
+      // Dedup — but join the in-flight fetch ONLY when it belongs to the current generation. An
+      // `invalidateQueries` bumps `generation`, so a fetch that started *before* the invalidation is
+      // superseded and must NOT satisfy this call (its data is pre-mutation); fall through and kick a
+      // fresh fetch instead of returning the stale in-flight one.
+      if (entry.promise !== undefined && entry.promiseGen === entry.generation) return entry.promise
+      if (!force && entry.state.status === "success" && !isStale())
+        return Promise.resolve(entry.state.data) // fresh cache hit — no fn call
+      const gen = entry.generation
+      setState({ ...entry.state, isFetching: true }) // show the background/initial fetch
+      const promise = (async () => {
+        try {
+          const data = await entry.fn()
+          // A newer generation (a later invalidate/refetch) owns the entry now — discard this result
+          // rather than publishing pre-mutation data as fresh or clearing `invalidated`. The fetch
+          // that superseded this one publishes the post-mutation data.
+          if (gen !== entry.generation) return data
+          entry.invalidated = false
+          setState({
+            status: "success",
+            data,
+            error: undefined,
+            isFetching: false,
+            updatedAt: now(),
+          })
+          return data
+        } catch (error) {
+          if (gen === entry.generation)
+            setState({ ...entry.state, status: "error", error, isFetching: false })
+          throw error
+        } finally {
+          // Clear the slot only if no newer fetch took ownership. A later generation's fetch
+          // overwrites `entry.promiseGen`, so `promiseGen === gen` means we're still the current
+          // in-flight fetch; if it differs, the fetch that superseded us owns `entry.promise` now.
+          if (entry.promiseGen === gen) entry.promise = undefined
+        }
+      })()
+      entry.promise = promise
+      entry.promiseGen = gen
+      return promise
+    }
+
+    entry.handle = {
+      snapshot: () => entry.state,
+      subscribe: (listener: () => void) => {
+        entry.subscribers++
+        entry.gcAt = undefined // in use again — cancel any pending eviction
+        entry.listeners.add(listener)
+        return () => {
+          entry.listeners.delete(listener)
+          entry.subscribers--
+          if (entry.subscribers === 0) entry.gcAt = now() + gcTime
+        }
+      },
+      fetch: () => run(false) as Promise<T>,
+      refetch: () => run(true) as Promise<T>,
+    }
+    cache.set(h, entry)
+    return entry.handle as QueryHandle<T>
+  }
+
+  const invalidateQueries = (keyOrPrefix: unknown): void => {
+    for (const entry of cache.values()) {
+      if (!keyMatchesPrefix(entry.key, keyOrPrefix)) continue
+      entry.invalidated = true // next fetch refetches even within staleTime
+      // Supersede any in-flight fetch begun before this point — its result is pre-mutation and must
+      // not resolve as "fresh" or clear `invalidated`. The refetch below (or the next `fetch()`)
+      // starts a new generation that publishes the post-mutation data.
+      entry.generation++
+      if (entry.subscribers > 0) void entry.handle.refetch().catch(() => {}) // refresh mounted now (best-effort)
+    }
+  }
+
+  return { query, invalidateQueries }
+}