@nifrajs/web 2.1.0 → 2.3.0

package/src/plugins/vite-server-only.ts

@@ -0,0 +1,75 @@
+/**
+ * `@nifrajs/web/plugins/vite-server-only` - the Vite half of the `.server` convention.
+ *
+ * A module named `*.server.ts(x)` is server-only: the Bun client build empties it so its import
+ * subtree - `node:` builtins, native modules, secrets - never reaches a browser. This does the same
+ * for Vite, in both the dev server and the production build.
+ *
+ * ## Why this exists separately
+ *
+ * The convention was implemented once, as a `Bun.build` plugin, which meant it held in exactly one of
+ * the four pipelines. `nifra build` emptied the module; `nifra dev` (Vite), a Vite production build,
+ * and `nifra dev --bun` all shipped it whole. A guard that holds in one pipeline and not the others is
+ * worse than none, because the file name reads as protection everywhere.
+ *
+ * `*.fn` already had this shape - a Bun plugin, a Vite plugin, and a refusal in the one pipeline that
+ * cannot transform. `.server` now matches it.
+ *
+ * ## Why `transform` and not `load`
+ *
+ * Vite resolves and reads the file itself; taking `load` would mean re-implementing its resolution.
+ * `transform` receives the source Vite already read, and returning replacement code discards the
+ * original along with its imports - so the server subtree is never followed. `enforce: "pre"` puts
+ * this ahead of framework transforms, which have no business seeing server code either.
+ */
+
+import {
+  SERVER_ONLY_MODULE,
+  SERVER_ONLY_REPLACEMENT,
+  viteServerOnlyReplacement,
+} from "../internal/server-boundary.ts"
+
+// Re-exported so a caller wiring its own bundler gets the matcher from the same owner the pipelines
+// use, rather than writing a fifth copy of the regex.
+export { SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, viteServerOnlyReplacement }
+
+/** The slice of a Vite/Rollup plugin this returns. Structural, so `vite` stays an optional peer. */
+export interface ServerOnlyEmptyPlugin {
+  readonly name: string
+  readonly enforce: "pre"
+  /** Applied only to the CLIENT build; the server build keeps the real module. */
+  readonly applyToEnvironment?: (environment: { readonly name: string }) => boolean
+  transform(
+    code: string,
+    id: string,
+    options?: { readonly ssr?: boolean },
+  ): { code: string; map: null } | null
+}
+
+/** Strips a Vite id's `?query` and `#hash` so the suffix test sees a plain path. */
+const bare = (id: string): string => id.split("?")[0]?.split("#")[0] ?? id
+
+/**
+ * Empty every `*.server` module in the client build.
+ *
+ * Client-only by construction: nifra passes this to the client build and the dev server, never to the
+ * SSR build, where the real module is what runs.
+ */
+export function viteServerOnlyEmpty(): ServerOnlyEmptyPlugin {
+  return {
+    name: "nifra:server-only-empty",
+    enforce: "pre",
+    // Vite 6+ environments: the SSR environment must keep the real module. Older Vite ignores this and
+    // relies on nifra only registering the plugin on the client side.
+    applyToEnvironment: (environment) => environment.name === "client",
+    transform(code, id, options) {
+      // Vite 5 ignores `applyToEnvironment` but supplies this transform context for SSR.
+      if (options?.ssr === true) return null
+      const path = bare(id)
+      if (!SERVER_ONLY_MODULE.test(path)) return null
+      // `map: null` is honest rather than lazy: the replacement shares no lines with the source, so any
+      // mapping would point a debugger at unrelated code.
+      return { code: viteServerOnlyReplacement(code), map: null }
+    },
+  }
+}

package/src/prerender.ts

@@ -2,7 +2,7 @@
  * 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.
+ * (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 (`*`)
@@ -13,7 +13,7 @@ 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`). */
+/** Minimal app surface the driver needs - just a fetch handler (a built `createWebApp`). */
 export interface PrerenderApp {
   fetch(req: Request): Response | Promise<Response>
 }
@@ -47,7 +47,7 @@ export interface PrerenderEntry {
 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
+  /** 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">>
 }
@@ -71,7 +71,7 @@ const outputPath = (root: string, file: string): string | 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 —
+ * (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.
@@ -88,7 +88,7 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
   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.
+      // 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
     }
@@ -104,7 +104,7 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
 
     // 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
+    // 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(
@@ -123,7 +123,7 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
         writeFileSync(dataAbs, await dataRes.text())
       }
     } else {
-      await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) — release the stream
+      await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
     }
 
     prerendered.push({ path, file, bytes: html.length, ...(dataFile ? { dataFile } : {}) })
@@ -131,7 +131,7 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
 
   for (const route of options.routes) {
     if (route.pattern.includes("*")) {
-      skipped.push({ path: route.pattern, reason: "catch-all/wildcard route — not supported" })
+      skipped.push({ path: route.pattern, reason: "catch-all/wildcard route - not supported" })
       continue
     }
     const mod = await route.load()
@@ -182,7 +182,7 @@ export interface CloudflarePagesRoutes {
 
 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`. */
+   * 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[]
@@ -195,7 +195,7 @@ export interface CloudflarePagesRoutesOptions {
  *
  * ⚠️ 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`.
+ * `/blog/*`) instead of listing every path - pass those via `staticGlobs` and a smaller `prerendered`.
  */
 export function cloudflarePagesRoutes(
   options: CloudflarePagesRoutesOptions,

package/src/public-dir.ts

@@ -0,0 +1,108 @@
+/**
+ * `public/` - user-authored static files, served identically in dev and in production.
+ *
+ * The asymmetry this closes: `nifra dev` served `public/` for free because the HMR path runs on Vite
+ * and Vite serves `public/` by default, while production had no `publicDir` concept at all. So a file
+ * worked all the way through development and 404'd the moment it was deployed. The failure is
+ * inverted - it appears only in production, and only for the assets nobody smoke-tests - and it has
+ * already shipped once as a self-hosted webfont that silently fell back to a system font in prod.
+ *
+ * One owner for both sides is the fix, not a second implementation that happens to agree today.
+ *
+ * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
+ * The names collide and the concepts do not: `publicPath` never covers user-authored files.
+ */
+import { realpath } from "node:fs/promises"
+import { normalize, resolve, sep } from "node:path"
+
+/** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
+ * user-authored file keeps its name across deploys, so it gets a day and a revalidation. */
+export interface PublicDirCache {
+  /** `cache-control` for content-hashed assets (default immutable, one year). */
+  readonly hashed?: string
+  /** `cache-control` for everything else under `public/` (default one day). */
+  readonly assets?: string
+}
+
+export interface ServePublicDirOptions {
+  /** Absolute path of the directory to serve. */
+  readonly dir: string
+  /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`). */
+  readonly hashedPrefix?: string
+  readonly cache?: PublicDirCache
+  /** Optional encoded URL-path allowlist. When present, route misses avoid a filesystem probe. */
+  readonly files?: ReadonlySet<string>
+}
+
+const IMMUTABLE = "public, max-age=31536000, immutable"
+const ONE_DAY = "public, max-age=86400"
+
+/**
+ * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
+ *
+ * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security
+ * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still
+ * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,
+ * because a blocklist over encodings is exactly the kind of check that gets bypassed.
+ */
+export function resolvePublicPath(root: string, pathname: string): string | undefined {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(pathname)
+  } catch {
+    return undefined // malformed percent-encoding: not a path we will guess at
+  }
+  // A NUL can truncate a path in a downstream syscall; refuse rather than normalize it away.
+  if (decoded.includes("\0")) return undefined
+  const rootResolved = resolve(root)
+  const candidate = resolve(rootResolved, `.${normalize(decoded)}`)
+  if (candidate !== rootResolved && !candidate.startsWith(rootResolved + sep)) return undefined
+  return candidate
+}
+
+/**
+ * Build a static-file handler for `dir`.
+ *
+ * Returns `undefined` on any miss so the caller **falls through to routing** - a static probe must
+ * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
+ * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
+ * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ */
+export function servePublicDir(
+  options: ServePublicDirOptions,
+): (request: Request) => Promise<Response | undefined> {
+  const root = resolve(options.dir)
+  const rootReal = realpath(root).catch(() => undefined)
+  const hashedPrefix = options.hashedPrefix ?? "/assets/"
+  const hashed = options.cache?.hashed ?? IMMUTABLE
+  const assets = options.cache?.assets ?? ONE_DAY
+
+  return async (request: Request): Promise<Response | undefined> => {
+    if (request.method !== "GET" && request.method !== "HEAD") return undefined
+    const { pathname } = new URL(request.url)
+    // A production manifest can reject page routes without touching the filesystem.
+    if (options.files !== undefined && !options.files.has(pathname)) return undefined
+    const abs = resolvePublicPath(root, pathname)
+    if (abs === undefined) return undefined
+    const [resolvedRoot, resolvedFile] = await Promise.all([
+      rootReal,
+      realpath(abs).catch(() => undefined),
+    ])
+    if (
+      resolvedRoot === undefined ||
+      resolvedFile === undefined ||
+      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))
+    ) {
+      return undefined
+    }
+    const file = Bun.file(resolvedFile)
+    if (!(await file.exists())) return undefined
+    const headers = new Headers({
+      "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+    })
+    // HEAD must not carry a body, but must otherwise match GET's headers.
+    return request.method === "HEAD"
+      ? new Response(null, { headers })
+      : new Response(file, { headers })
+  }
+}

package/src/query.ts

@@ -1,8 +1,8 @@
 /**
- * The agnostic keyed query-cache — a `query(key, fn)` primitive with in-flight dedup, `staleTime`
+ * The agnostic keyed query-cache - a `query(key, fn)` primitive with in-flight dedup, `staleTime`
  * freshness, prefix `invalidateQueries`, imperative cache read/write, prefetch, SSR dehydrate/hydrate,
  * infinite (paged) queries, and standalone mutations. Pure logic, no `window`, no framework, no
- * `Date.now`/timers (the clock is injected) — so it unit-tests deterministically and is safe to import
+ * `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`/`useMutation`/`createQuery`)
  * subscribes to a query/mutation's `subscribe`/`snapshot` store (the same shape the router + fetchers
  * use).
@@ -15,13 +15,13 @@
 /** 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
+/** 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). */
+  /** 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
@@ -46,14 +46,14 @@ export interface QueryOptions {
 }
 
 export interface QueryClientOptions {
-  /** Monotonic clock in ms — injected so the core stays deterministic + testable; the adapter binding
+  /** 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). */
+  /** Hard cap on cached entries - LRU-evict the oldest *unsubscribed* entry past it (default 1000). */
   readonly max?: number
 }
 
@@ -65,7 +65,7 @@ export interface InfiniteData<T, P> {
 }
 
 /** Options for an {@link InfiniteQueryHandle}. `getNextPageParam` (required) derives the param for the
- * next page from the last page — return `undefined`/`null` to signal there is no next page. */
+ * next page from the last page - return `undefined`/`null` to signal there is no next page. */
 export interface InfiniteQueryOptions<T, P> extends QueryOptions {
   /** The param the FIRST page is fetched with. */
   readonly initialPageParam: P
@@ -104,7 +104,7 @@ export interface InfiniteQueryHandle<T, P> {
   hasPreviousPage: () => boolean
 }
 
-/** A serializable snapshot of the cache's successful queries — the SSR→client bridge payload. */
+/** A serializable snapshot of the cache's successful queries - the SSR→client bridge payload. */
 export interface DehydratedState {
   readonly queries: ReadonlyArray<{
     readonly key: unknown
@@ -144,7 +144,7 @@ export interface QueryClient {
 
 /**
  * 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
+ * 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 {
@@ -179,7 +179,7 @@ interface Entry {
   staleTime: number
   state: QueryState
   promise: Promise<unknown> | undefined
-  /** The {@link generation} the in-flight {@link promise} started at — so a fetch begun *before* an
+  /** 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. */
@@ -217,7 +217,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
   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.
+  // 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) {
@@ -251,8 +251,8 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       handle: undefined as unknown as QueryHandle,
     }
     const emit = (): void => {
-      // Iterate the live set — no per-emit copy (the common case is 0–1 subscribers). Contract: a
-      // listener must not synchronously subscribe/unsubscribe during notification — `useSyncExternalStore`/
+      // Iterate the live set - no per-emit copy (the common case is 0-1 subscribers). 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()
@@ -265,19 +265,19 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       entry.invalidated || now() - entry.state.updatedAt >= entry.staleTime
 
     entry.run = (force: boolean): Promise<unknown> => {
-      // Dedup — but join the in-flight fetch ONLY when it belongs to the current generation. An
+      // 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
+        return Promise.resolve(entry.state.data) // fresh cache hit - no fn call
       const gen = entry.generation
       entry.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
+          // 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
@@ -304,7 +304,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       snapshot: () => entry.state,
       subscribe: (listener: () => void) => {
         entry.subscribers++
-        entry.gcAt = undefined // in use again — cancel any pending eviction
+        entry.gcAt = undefined // in use again - cancel any pending eviction
         entry.listeners.add(listener)
         return () => {
           entry.listeners.delete(listener)
@@ -342,7 +342,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     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
+      // 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++
@@ -358,7 +358,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
   }
 
   const setQueryData = <T>(key: unknown, updater: T | ((prev: T | undefined) => T)): void => {
-    // Create a placeholder entry if none exists — its `fn` throws until a real `query(key, fn)` re-binds
+    // Create a placeholder entry if none exists - its `fn` throws until a real `query(key, fn)` re-binds
     // it, so a `setQueryData` for a key nobody queries yet never triggers a fetch on its own.
     const entry = upsert(
       key,
@@ -370,7 +370,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     const prev = entry.state.status === "success" ? (entry.state.data as T) : undefined
     const data =
       typeof updater === "function" ? (updater as (p: T | undefined) => T)(prev) : updater
-    // A direct write is the new truth — bump the generation so any in-flight fetch can't overwrite it,
+    // A direct write is the new truth - bump the generation so any in-flight fetch can't overwrite it,
     // and clear the invalidated flag (the caller just supplied fresh data).
     entry.generation++
     entry.invalidated = false
@@ -629,7 +629,7 @@ const IDLE_MUTATION: MutationState<unknown, unknown> = Object.freeze({
 })
 
 /**
- * Create a standalone mutation state machine — framework-agnostic, so a per-adapter `useMutation`
+ * Create a standalone mutation state machine - framework-agnostic, so a per-adapter `useMutation`
  * binding just subscribes to it. Single-flight by a monotonic token: overlapping `mutate` calls each
  * run their `fn`, but only the latest publishes state (an older, slower response can't clobber a newer
  * one). The callbacks fire in TanStack order: `onMutate` (before), then `onSuccess`/`onError`, then
@@ -667,7 +667,7 @@ export function createMutation<TData, TVariables>(
     mutate: async (variables) => {
       const mine = ++token
       setState({ status: "pending", data: undefined, error: undefined, variables })
-      // Only await a callback when one is actually supplied — an `await undefined` would insert a
+      // Only await a callback when one is actually supplied - an `await undefined` would insert a
       // needless microtask before the mutationFn runs (and complicates single-flight timing).
       if (cbs.onMutate !== undefined) await cbs.onMutate(variables)
       try {