@jasonshimmy/vite-plugin-cer-app 0.6.0 → 0.7.0

package/src/runtime/isr-handler.ts

@@ -0,0 +1,183 @@
+/**
+ * createIsrHandler — portable stale-while-revalidate ISR factory.
+ *
+ * Wraps any Express-compatible SSR handler with an in-memory ISR cache.
+ * Routes that export `meta.ssg.revalidate` get cached for the declared TTL.
+ *
+ * Usage (Express):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use(createIsrHandler(routes, handler))
+ *
+ * Usage (Hono):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use('*', createIsrHandler(routes, handler))
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export interface IsrCacheEntry {
+  html: string
+  headers: Record<string, string>
+  statusCode: number
+  builtAt: number
+  revalidate: number
+  revalidating: boolean
+}
+
+export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => unknown
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function _matchPattern(pattern: string, urlPath: string): boolean {
+  const norm = (s: string) => s.replace(/\/+$/, '') || '/'
+  if (norm(pattern) === norm(urlPath)) return true
+  const regexStr =
+    '^' +
+    norm(pattern)
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/:[^/]+\*/g, '.*')
+      .replace(/:[^/]+/g, '[^/]+') +
+    '$'
+  return new RegExp(regexStr).test(norm(urlPath))
+}
+
+function _findRevalidate(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  urlPath: string,
+): number | null {
+  for (const route of routes) {
+    if (_matchPattern(route.path, urlPath)) {
+      const ssg = route.meta?.ssg as Record<string, unknown> | undefined
+      if (typeof ssg?.revalidate === 'number') return ssg.revalidate
+      return null
+    }
+  }
+  return null
+}
+
+async function _renderForCache(
+  urlPath: string,
+  handler: SsrHandlerFn,
+  revalidate: number,
+): Promise<IsrCacheEntry | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = []
+    const capturedHeaders: Record<string, string | string[]> = {}
+    let capturedStatus = 200
+
+    const fakeRes = {
+      get statusCode() { return capturedStatus },
+      set statusCode(v: number) { capturedStatus = v },
+      setHeader(name: string, value: string | string[]) {
+        capturedHeaders[name.toLowerCase()] = value
+      },
+      write(chunk: string | Buffer) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf-8'))
+      },
+      end(body?: string | Buffer) {
+        if (body !== undefined) {
+          chunks.push(Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf-8'))
+        }
+        resolve({
+          html: Buffer.concat(chunks).toString('utf-8'),
+          headers: Object.fromEntries(
+            Object.entries(capturedHeaders).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : v]),
+          ),
+          statusCode: capturedStatus,
+          builtAt: Date.now(),
+          revalidate,
+          revalidating: false,
+        })
+      },
+    } as unknown as ServerResponse
+
+    const fakeReq = {
+      url: urlPath,
+      method: 'GET',
+      headers: { accept: 'text/html' },
+    } as IncomingMessage
+
+    try {
+      const result = handler(fakeReq, fakeRes)
+      if (result && typeof (result as Promise<void>).catch === 'function') {
+        ;(result as Promise<void>).catch(() => resolve(null))
+      }
+    } catch {
+      resolve(null)
+    }
+  })
+}
+
+function _serveFromCache(entry: IsrCacheEntry, res: ServerResponse, status: 'HIT' | 'STALE'): void {
+  res.statusCode = entry.statusCode
+  for (const [name, value] of Object.entries(entry.headers)) {
+    res.setHeader(name, value)
+  }
+  res.setHeader('X-Cache', status)
+  res.end(entry.html)
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Wraps an SSR handler with stale-while-revalidate ISR caching.
+ *
+ * Routes that declare `meta.ssg.revalidate` in the `routes` array are cached
+ * in memory. After the TTL expires the stale response is served immediately
+ * while a fresh render runs in the background (stale-while-revalidate).
+ *
+ * Routes without a `revalidate` value are passed through to the handler directly.
+ */
+export function createIsrHandler(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  handler: SsrHandlerFn,
+): SsrHandlerFn {
+  const cache = new Map<string, IsrCacheEntry>()
+
+  return async (req: IncomingMessage, res: ServerResponse): Promise<unknown> => {
+    const urlPath = (req.url ?? '/').split('?')[0]
+    const revalidate = _findRevalidate(routes, urlPath)
+
+    if (revalidate === null) {
+      return handler(req, res)
+    }
+
+    const cached = cache.get(urlPath)
+    const now = Date.now()
+
+    if (cached) {
+      const ageSeconds = (now - cached.builtAt) / 1000
+      if (ageSeconds < cached.revalidate) {
+        _serveFromCache(cached, res, 'HIT')
+        return
+      }
+      if (!cached.revalidating) {
+        cached.revalidating = true
+        _serveFromCache(cached, res, 'STALE')
+        const timeout = setTimeout(() => { if (cached) cached.revalidating = false }, 30_000)
+        _renderForCache(urlPath, handler, revalidate).then((entry) => {
+          clearTimeout(timeout)
+          if (entry) cache.set(urlPath, entry)
+          else if (cached) cached.revalidating = false
+        }).catch(() => {
+          clearTimeout(timeout)
+          if (cached) cached.revalidating = false
+        })
+        return
+      }
+      _serveFromCache(cached, res, 'STALE')
+      return
+    }
+
+    // Cache miss — render, cache, then serve.
+    const entry = await _renderForCache(urlPath, handler, revalidate)
+    if (entry) {
+      cache.set(urlPath, entry)
+      _serveFromCache(entry, res, 'HIT')
+    } else {
+      await handler(req, res)
+    }
+  }
+}

package/src/types/page.ts

@@ -32,6 +32,20 @@ export interface PageMeta {
    * @example export const meta = { transition: 'fade' }
    */
   transition?: string | boolean
+  /**
+   * Per-route rendering strategy. Overrides the global `mode` for this route.
+   *
+   * - `'server'` — always render server-side, never pre-render. In SSG mode
+   *   the route is skipped during the static build.
+   * - `'static'` — always serve pre-rendered static HTML. In the SSR preview
+   *   server the pre-rendered file is served from disk; falls back to SSR if
+   *   not found.
+   * - `'spa'`    — client-only. In SSR mode the server returns the SPA shell
+   *   (index.html) without rendering. In SSG mode the route is skipped.
+   *
+   * @example export const meta = { render: 'server' }
+   */
+  render?: 'static' | 'server' | 'spa'
 }
 
 export interface PageLoaderContext<P extends Record<string, string> = Record<string, string>> {