@zerotal/inertia 1.0.0

package/src/index.ts

@@ -0,0 +1,102 @@
+/**
+ * The Inertia.js adapter for Zerotal — build React or Vue single-page apps with
+ * no separate API layer.
+ *
+ * Controllers return {@link inertia | `inertia('PageName', props)`} instead of
+ * JSON or HTML: on a full page load the adapter renders the HTML shell, and on
+ * subsequent visits it returns a JSON page object that the Inertia client swaps
+ * into the current page component. {@link share | Shared props} expose global
+ * data (the authenticated user, flash messages) to every page, the
+ * {@link optional}/{@link lazy}/{@link defer} prop helpers control what is sent
+ * on partial reloads, and {@link SsrHandler | SSR} renders the first paint on
+ * the server.
+ *
+ * @example Return an Inertia page from a controller
+ * ```ts
+ * import { inertia } from "@zerotal/inertia";
+ *
+ * export async function index(ctx) {
+ *   const users = await User.query().get();
+ *   return inertia("Users/Index", { users });
+ * }
+ * ```
+ *
+ * @example Share global props at boot
+ * ```ts
+ * import { share } from "@zerotal/inertia";
+ *
+ * share("appName", () => config("app.name"));
+ * ```
+ *
+ * @remarks
+ * Register `InertiaProvider`. React consumers need `react`/`react-dom`; Vue
+ * consumers need `vue`/`@inertiajs/vue3` (declare whichever you use). Requires
+ * **Bun ≥ 1.1**.
+ *
+ * @packageDocumentation
+ */
+
+// @zerotal/inertia — public API
+
+// Side-effect import: augments @zerotal/core RouterMacros so Router.inertia() is typed.
+import "./augment.ts";
+
+export { inertiaRoute } from "./route.ts";
+
+export {
+  inertia,
+  inertiaStream,
+  buildPageObject,
+  _setHtmlTemplate,
+  _getHtmlTemplate,
+} from "./inertia.ts";
+export { InertiaProvider } from "./provider/InertiaProvider.ts";
+export { InertiaMiddleware } from "./middleware/InertiaMiddleware.ts";
+export { PrecognitionMiddleware } from "./middleware/PrecognitionMiddleware.ts";
+export { sharedProps } from "./SharedProps.ts";
+export { assetVersion, setAssetVersion } from "./version.ts";
+export { generatePageRegistry } from "./PageRegistry.ts";
+export { detectVuePlugin } from "./vuePlugin.ts";
+export type { PageObject, InertiaProviderOptions } from "./types.ts";
+
+// Unified facade
+export { Inertia } from "./facades/Inertia.ts";
+
+// Prop wrappers + factories (v3 data props)
+export {
+  InertiaProp,
+  OptionalProp,
+  AlwaysProp,
+  DeferProp,
+  MergeProp,
+  InfiniteScrollProp,
+  optional,
+  lazy,
+  always,
+  defer,
+  merge,
+  deepMerge,
+  scroll,
+} from "./props/PropTypes.ts";
+export type { PropFactory, MergeConfig, PaginatorLike, ScrollConfig } from "./props/PropTypes.ts";
+export { resolveProps } from "./props/resolveProps.ts";
+export type { ResolvedPage } from "./props/resolveProps.ts";
+
+// Shared props registry
+export { share } from "./share.ts";
+
+// History encryption
+export { encryptHistory, clearHistory, setHistoryEncryptionDefault } from "./historyState.ts";
+
+// External / fragment redirects
+export { location } from "./location.ts";
+
+// Config factory
+export { InertiaConfig } from "./config.ts";
+export type { InertiaConfigShape } from "./config.ts";
+
+// SSR handler (for direct use or testing)
+export { SsrHandler } from "./SsrHandler.ts";
+
+// Typed errors
+export { InertiaError, InertiaTemplateNotLoadedError, InvalidComponentError } from "./errors.ts";

package/src/inertia.ts

@@ -0,0 +1,347 @@
+import { config, RequestContext } from "@zerotal/core";
+import { statSync } from "node:fs";
+import { InertiaTemplateNotLoadedError, InvalidComponentError } from "./errors.ts";
+import { DEFAULT_PAGES_DIR } from "./config.ts";
+import { sharedProps } from "./SharedProps.ts";
+import { assetVersion } from "./version.ts";
+import { resolveProps } from "./props/resolveProps.ts";
+import { readHistoryFlags } from "./historyState.ts";
+import { allSharedKeys } from "./share.ts";
+import { resolvePageModule, renderInertiaPage } from "./ssr/renderPage.ts";
+import type { PageObject } from "./types.ts";
+
+/**
+ * Build the full Inertia page object for the current request: merges shared props, runs the v3
+ * prop-resolution pipeline (partial reloads, lazy/optional/always, defer, merge, once), and attaches
+ * history-encryption flags and the shared-prop key list.
+ *
+ * @param component - Page component name (path relative to the pages dir, without extension), e.g. `"Users/Index"`.
+ * @param props - Raw props from the controller; may include prop wrappers (`optional`/`defer`/`merge`/`scroll`/…) that the resolver evaluates.
+ * @returns The serialisable {@link PageObject} embedded into the HTML (first load) or returned as JSON (XHR visits).
+ * @internal Shared plumbing behind {@link inertia} and {@link inertiaStream}; app authors call those instead.
+ */
+export async function buildPageObject(
+  component: string,
+  props: Record<string, unknown>,
+): Promise<PageObject> {
+  const ctx = RequestContext.get();
+  const merged = { ...sharedProps(), ...props };
+  const resolved = await resolveProps(merged, ctx.request.headers, component);
+
+  const page: PageObject = {
+    component,
+    props: resolved.props,
+    url: ctx.url.pathname + (ctx.url.search || ""),
+    version: assetVersion(),
+  };
+
+  if (resolved.deferredProps) page.deferredProps = resolved.deferredProps;
+  if (resolved.mergeProps) page.mergeProps = resolved.mergeProps;
+  if (resolved.prependProps) page.prependProps = resolved.prependProps;
+  if (resolved.deepMergeProps) page.deepMergeProps = resolved.deepMergeProps;
+  if (resolved.matchPropsOn) page.matchPropsOn = resolved.matchPropsOn;
+  if (resolved.scrollProps) page.scrollProps = resolved.scrollProps;
+  if (resolved.onceProps) page.onceProps = resolved.onceProps;
+  if (resolved.rescuedProps) page.rescuedProps = resolved.rescuedProps;
+
+  const sharedPresent = allSharedKeys().filter((k) => k in resolved.props);
+  if (sharedPresent.length) page.sharedProps = sharedPresent;
+
+  const history = readHistoryFlags();
+  if (history.encryptHistory) page.encryptHistory = true;
+  if (history.clearHistory) page.clearHistory = true;
+
+  return page;
+}
+
+// Loaded once at boot by InertiaProvider.onBooting()
+// Never read from disk per-request
+let _htmlTemplate = "";
+let _pagesDir = "";
+
+/**
+ * Cache the root HTML template (the `resources/app.html` shell containing the
+ * `<!-- @inertia -->` placeholder). Called once by `InertiaProvider` during boot
+ * so `inertia()` / `inertiaStream()` never touch disk per request.
+ *
+ * @param html - The full HTML document read from the configured `htmlTemplate`.
+ * @internal
+ */
+export function _setHtmlTemplate(html: string): void {
+  _htmlTemplate = html;
+}
+
+/**
+ * The cached HTML template (empty string until `InertiaProvider` boots).
+ *
+ * @returns The template string, or `""` if not yet loaded.
+ * @internal
+ */
+export function _getHtmlTemplate(): string {
+  return _htmlTemplate;
+}
+
+/**
+ * Override the pages directory (absolute path) used to resolve page modules for
+ * SSR / streaming. Normally derived from `inertia.pagesDir` config; set explicitly
+ * by `InertiaProvider` at boot.
+ *
+ * @internal
+ */
+export function _setPagesDir(dir: string): void {
+  _pagesDir = dir;
+}
+
+/**
+ * The absolute pages directory used to locate page components, falling back to
+ * `<cwd>/<inertia.pagesDir>` (default `resources/js/pages`).
+ *
+ * @internal
+ */
+export function _getPagesDir(): string {
+  return _pagesDir || `${process.cwd()}/${config.safe("inertia.pagesDir", DEFAULT_PAGES_DIR)}`;
+}
+
+/**
+ * In dev (`--dev-worker`) append a cache-busting `?v=<mtime>` to local JS/CSS
+ * asset URLs in the served HTML, so the browser fetches a freshly-rebuilt
+ * bundle instead of a stale cached copy.
+ *
+ * The token is the asset file's modification time: unchanged assets keep a
+ * stable URL (and stay cached), while a rebuild changes the URL and forces a
+ * re-fetch. No-op in production, where assets are served as-is.
+ *
+ * @internal
+ */
+function _devBustAssets(html: string): string {
+  if (!process.argv.includes("--dev-worker")) return html;
+  const root = `${process.cwd()}/public`;
+  return html.replace(
+    /((?:href|src)=")(\/[^"?]+\.(?:js|css))(")/g,
+    (match, pre: string, url: string, post: string) => {
+      try {
+        const mtime = Math.floor(statSync(`${root}${url}`).mtimeMs);
+        return `${pre}${url}?v=${mtime}${post}`;
+      } catch {
+        return match; // asset not found under public/ — leave the URL untouched
+      }
+    },
+  );
+}
+
+/**
+ * Render an Inertia page server-side and return a streaming HTML Response.
+ *
+ * Splits the HTML template at `<!-- @inertia -->` and writes the server-rendered
+ * component between the prefix and suffix, improving TTFB over `inertia()` since
+ * the browser can start parsing the `<head>` before the component is sent.
+ *
+ * Framework-aware: React pages (`.tsx`) stream chunk-by-chunk via
+ * `react-dom/server`'s `renderToReadableStream`; Vue pages (`.vue`) are rendered
+ * to a string via `@inertiajs/vue3`'s SSR mode (head tags injected into
+ * `<head>`) and flushed after the prefix. The component is resolved from
+ * `<cwd>/<inertia.pagesDir>/<component>.{vue,tsx}` (defaults to `resources/js/pages`).
+ *
+ * Like {@link inertia}, this reads the current request from `RequestContext` and
+ * writes the streaming `Response` onto `ctx.response` as a side effect (returns `void`).
+ * Reach it from a controller via `Inertia.stream(...)`.
+ *
+ * @param component - Page component name (path relative to the pages dir, no extension), e.g. `"Posts/Show"`.
+ * @param props - Props passed to the page; may include prop wrappers (`optional`/`defer`/`merge`/…).
+ * @throws {@link InertiaTemplateNotLoadedError} When the HTML template has not been loaded (InertiaProvider not registered).
+ * @throws {@link InvalidComponentError} When the component name contains path-traversal sequences.
+ *
+ * @example
+ * ```ts
+ * async show(http: HttpContext): Promise<void> {
+ *   const post = await Post.findOrFail(http.params.id);
+ *   return Inertia.stream('Posts/Show', { post });
+ * }
+ * ```
+ */
+export async function inertiaStream(
+  component: string,
+  props: Record<string, unknown> = {},
+): Promise<void> {
+  const ctx = RequestContext.get();
+
+  if (!_htmlTemplate) {
+    throw new InertiaTemplateNotLoadedError();
+  }
+
+  if (component.includes("..") || component.startsWith("/")) {
+    throw new InvalidComponentError(component, "contains an unsafe path");
+  }
+
+  const pageObject = await buildPageObject(component, props);
+
+  const [prefix = "", suffix = ""] = _devBustAssets(_htmlTemplate).split("<!-- @inertia -->");
+
+  const { modPath, framework } = await resolvePageModule(_getPagesDir(), component);
+  const encoder = new TextEncoder();
+  const responseInit = {
+    headers: { "Content-Type": "text/html; charset=utf-8", Vary: "X-Inertia" },
+  };
+
+  if (framework === "react") {
+    // React's stream is just the component's inner HTML, so Zerotal wraps it in
+    // the app root and serialises the pageObject into the data-page script.
+    const safeJson = JSON.stringify(pageObject)
+      .replace(/</g, "\\u003c")
+      .replace(/>/g, "\\u003e")
+      .replace(/&/g, "\\u0026")
+      .replace(/\//g, "\\/");
+    const openTag = `<div id="app">`;
+    const closeBlock = `</div>\n    <script type="application/json" data-page="app">${safeJson}</script>`;
+
+    const [reactMod, serverMod, pageMod] = await Promise.all([
+      import("react") as Promise<{ createElement(type: unknown, props: unknown): unknown }>,
+      import("react-dom/server") as Promise<{
+        renderToReadableStream(el: unknown): Promise<ReadableStream<Uint8Array>>;
+      }>,
+      import(modPath) as Promise<{ default: unknown }>,
+    ]);
+
+    const element = reactMod.createElement(pageMod.default, pageObject.props);
+    const reactStream = await serverMod.renderToReadableStream(element);
+
+    const readable = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        controller.enqueue(encoder.encode(prefix + openTag));
+        const reader = reactStream.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        controller.enqueue(encoder.encode(closeBlock + suffix));
+        controller.close();
+      },
+    });
+
+    ctx.response = new Response(readable, responseInit);
+    return;
+  }
+
+  // Vue: @inertiajs/vue3's SSR mode already emits the full
+  // `<div id="app" data-page="…">…</div>` root (the complete pageObject is
+  // serialised into data-page), so inject it directly in place of the
+  // placeholder — no extra app-div wrapper or data-page script. Any <Head>
+  // tags are injected into <head>.
+  const { body, head } = await renderInertiaPage(pageObject, modPath, framework);
+  const prefixWithHead =
+    head.length > 0 ? prefix.replace("</head>", `${head.join("")}</head>`) : prefix;
+
+  const readable = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encoder.encode(prefixWithHead + body + suffix));
+      controller.close();
+    },
+  });
+
+  ctx.response = new Response(readable, responseInit);
+}
+
+/**
+ * Render an Inertia page from a controller action — the primary way to return a
+ * page from Zerotal's Inertia adapter.
+ *
+ * You name a client-side page component and hand it a bag of props; Inertia takes
+ * care of showing that component with those props, so you build a React/Vue SPA
+ * without writing a separate JSON API. The component name is a path (relative to
+ * the configured pages dir, without extension) resolving to a page under
+ * `resources/js/pages`, e.g. `"Users/Index"` → `resources/js/pages/Users/Index.tsx`.
+ *
+ * @remarks
+ * Reads the current request from `RequestContext` (AsyncLocalStorage) — no `ctx`
+ * argument needed — and assigns the outgoing `Response` to `ctx.response` as a side
+ * effect, hence the `Promise<void>` return. The two response shapes it produces are
+ * what "Inertia" means on the wire:
+ *
+ * - **First / full-page load** (no `X-Inertia` header): the full HTML shell from
+ *   the app template with the page object serialised into a `<script data-page>`
+ *   tag (HTML-escaped so it can't break out of the script). The client-side
+ *   Inertia runtime boots from it.
+ * - **Subsequent visits** (`X-Inertia: true` XHR): a JSON body containing only the
+ *   page object, carrying `X-Inertia: true` and `Vary: X-Inertia` (the latter stops
+ *   the browser from caching JSON as HTML and rendering raw JSON on Back/Refresh).
+ *
+ * Before responding, props are run through the Inertia v3 resolution pipeline (see
+ * {@link buildPageObject} / `resolveProps`): the app's shared props (auth, flash,
+ * errors, plus anything from {@link share}) are merged in; **partial reloads** honour
+ * the client's `only`/`except` headers so a visit can refetch just a few props; and
+ * prop wrappers control evaluation — plain values are sent as-is, functions and
+ * `optional`/`lazy`/`defer` props are evaluated only when actually included (deferred
+ * ones load in a follow-up request), while `always`, `merge`/`deepMerge`, `scroll`,
+ * and `once` props are advertised so the client merges rather than replaces.
+ *
+ * For streaming SSR (better TTFB) use {@link inertiaStream} instead; to force a
+ * full-page/external redirect use {@link location}.
+ *
+ * @param component - Page component name/path relative to the pages dir, without extension (e.g. `"Users/Index"`).
+ * @param props - Props for the page. Values may be plain data or prop wrappers (`optional`/`defer`/`merge`/`scroll`/…). Defaults to `{}`.
+ * @returns A promise that resolves once `ctx.response` has been set (no value).
+ * @throws {@link InertiaTemplateNotLoadedError} On a full-page load when the HTML template has not been loaded (InertiaProvider not registered).
+ *
+ * @example
+ * ```ts
+ * // app/controllers/UserController.ts
+ * async index(http: HttpContext): Promise<void> {
+ *   const users = await User.query().orderBy('name').get();
+ *   return inertia('Users/Index', { users });
+ * }
+ * ```
+ */
+export async function inertia(
+  component: string,
+  props: Record<string, unknown> = {},
+): Promise<void> {
+  const ctx = RequestContext.get();
+  const isInertiaRequest = ctx.request.headers.get("X-Inertia") === "true";
+
+  const pageObject = await buildPageObject(component, props);
+
+  if (isInertiaRequest) {
+    // Subsequent XHR navigation — JSON only
+    // Vary: X-Inertia is CRITICAL — prevents browser from caching
+    // JSON as HTML, which would show raw JSON on browser Back/Refresh
+    ctx.response = new Response(JSON.stringify(pageObject), {
+      headers: {
+        "Content-Type": "application/json",
+        "X-Inertia": "true",
+        Vary: "X-Inertia",
+      },
+    });
+    return;
+  }
+
+  if (!_htmlTemplate) {
+    throw new InertiaTemplateNotLoadedError();
+  }
+
+  // Inject pageObject into the HTML template.
+  // Escape characters that would break HTML parsing inside a script tag.
+  // </script> → <\/script>, < → <, > → >
+  const safeJson = JSON.stringify(pageObject)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\//g, "\\/");
+
+  const html = _devBustAssets(_htmlTemplate).replace(
+    "<!-- @inertia -->",
+    `<div id="app"></div>\n    ` +
+      `<script type="application/json" data-page="app">${safeJson}</script>`,
+  );
+
+  ctx.response = new Response(html, {
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      Vary: "X-Inertia",
+    },
+  });
+}

package/src/location.ts

@@ -0,0 +1,35 @@
+import { RequestContext } from "@zerotal/core";
+
+/**
+ * Redirect to an external URL, or force a full-page (non-Inertia) visit to an internal one.
+ *
+ * @remarks
+ * A normal Inertia visit expects a JSON page object, so it cannot follow an ordinary
+ * redirect off the SPA. For an Inertia XHR this helper responds `409 Conflict` with an
+ * `X-Inertia-Location` header, which
+ * tells the client to do a hard `window.location` navigation; for a plain request it
+ * responds with a standard `302` redirect. Use it for third-party URLs (payment
+ * portals, OAuth providers) or any target that must leave the SPA.
+ *
+ * Reads the current request from `RequestContext` and sets `ctx.response` as a side
+ * effect (returns `void`), like {@link inertia}.
+ *
+ * @param url - The absolute or relative URL to send the browser to.
+ *
+ * @example
+ * ```ts
+ * // Send the user off to an external billing portal.
+ * async billing(http: HttpContext): Promise<void> {
+ *   const session = await stripe.createBillingSession(Auth.id());
+ *   return location(session.url);
+ * }
+ * ```
+ */
+export function location(url: string): void {
+  const ctx = RequestContext.get();
+  const isInertia = ctx.request.headers.get("X-Inertia") === "true";
+
+  ctx.response = isInertia
+    ? new Response(null, { status: 409, headers: { "X-Inertia-Location": url } })
+    : new Response(null, { status: 302, headers: { Location: url } });
+}

package/src/middleware/InertiaMiddleware.ts

@@ -0,0 +1,95 @@
+import type { NextFn, HttpContext } from "@zerotal/core";
+import { BaseMiddleware, withHeaders } from "@zerotal/core";
+import { assetVersion } from "../version.ts";
+
+/**
+ * Must be registered as global middleware in Application.use()
+ * or in AppServiceProvider before other middleware.
+ *
+ * Handles the Inertia protocol requirements:
+ *
+ * 1. 303 redirect after POST/PUT/DELETE
+ *    When a non-GET Inertia request results in a standard 302 redirect,
+ *    Inertia requires a 303 to force the browser to GET the redirect target.
+ *    Without this, browsers repeat the original POST method on the redirect.
+ *
+ * 2. Asset version mismatch (409 Conflict)
+ *    If the client sends X-Inertia-Version that differs from the server's
+ *    current asset version, respond with 409 and X-Inertia-Location header.
+ *    This triggers a full page reload on the client to pick up new assets.
+ *
+ * 3. Always set Vary: X-Inertia on all responses
+ *    Ensures browser cache treats HTML and JSON versions as distinct.
+ */
+export class InertiaMiddleware extends BaseMiddleware {
+  protected options: {} = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const isInertia = http.request.headers.get("X-Inertia") === "true";
+
+    // Asset version check — only for Inertia XHR GET requests
+    if (isInertia && http.request.method === "GET") {
+      const clientVersion = http.request.headers.get("X-Inertia-Version");
+      const serverVersion = assetVersion();
+
+      if (clientVersion && serverVersion && clientVersion !== serverVersion) {
+        // Client has stale assets — force full reload
+        return new Response(null, {
+          status: 409,
+          headers: {
+            "X-Inertia-Location": http.url.href,
+          },
+        });
+      }
+    }
+
+    // Run the rest of the pipeline
+    const response = await next();
+
+    // After the pipeline: apply response transformations
+    if (!response) return;
+
+    const status = response.status;
+    const method = http.request.method;
+    const isRedirect = [301, 302, 303].includes(status);
+
+    // Fragment redirects: a redirect whose target carries a URL fragment (#...) on an Inertia
+    // request becomes a 409 + X-Inertia-Redirect, so the client performs a standard Inertia visit
+    // (preserving the fragment) instead of a full reload.
+    if (isInertia && isRedirect) {
+      const target = response.headers.get("Location") ?? "";
+      if (target.includes("#")) {
+        // Same header-preservation concern as the 303 branch below.
+        const headers = new Headers(response.headers);
+        headers.delete("Location");
+        headers.set("X-Inertia-Redirect", target);
+        headers.set("X-Inertia", "true");
+        return new Response(null, { status: 409, headers });
+      }
+    }
+
+    // Convert 302 to 303 for non-GET Inertia redirects
+    // Inertia requires 303 so browsers use GET on the redirect target
+    if (isInertia && [301, 302].includes(status) && method !== "GET") {
+      // Carry the original headers over. Rebuilding the Response from just `Location` dropped
+      // every other header the handler set — most importantly `Set-Cookie`, so `POST /login`
+      // returned a 303 to /dashboard with the session cookie discarded and the user still
+      // logged out.
+      const headers = new Headers(response.headers);
+      headers.set("Location", response.headers.get("Location") ?? "/");
+      headers.set("X-Inertia", "true");
+      return new Response(null, { status: 303, headers });
+    }
+
+    // Never wrap streaming responses (e.g. SSE) — re-creating the Response
+    // object with new Headers would transfer and potentially disturb the
+    // ReadableStream body, breaking long-lived connections.
+    const contentType = response.headers.get("Content-Type") ?? "";
+    if (contentType.startsWith("text/event-stream")) return response;
+
+    // Ensure Vary: X-Inertia is present on all responses
+    // Required so browser cache does not confuse HTML and JSON versions
+    if (response.headers.has("Vary")) return response;
+    return withHeaders(response, { Vary: "X-Inertia" });
+  }
+}

package/src/middleware/PrecognitionMiddleware.ts

@@ -0,0 +1,33 @@
+import type { NextFn, HttpContext } from "@zerotal/core";
+import { BaseMiddleware, withHeaders } from "@zerotal/core";
+
+/**
+ * Precognition support.
+ *
+ * Inertia "precognition" lets the client validate a form against the server's real rules
+ * without running the controller's side effects. The validation itself happens inside
+ * `FormRequest.validate()` (which short-circuits with a 204 or 422 when `Precognition: true`); this
+ * middleware just guarantees every response to a precognitive request carries `Vary: Precognition`
+ * so caches don't mix precognition and normal responses.
+ *
+ * Register it globally (before route middleware) when using precognitive forms.
+ */
+export class PrecognitionMiddleware extends BaseMiddleware {
+  protected options: {} = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const isPrecognitive = http.request.headers.get("Precognition") === "true";
+
+    const response = await next();
+
+    if (isPrecognitive && response) {
+      const vary = response.headers.get("Vary");
+      const merged = !vary
+        ? "Precognition"
+        : vary.split(",").some((v) => v.trim() === "Precognition")
+          ? vary
+          : `${vary}, Precognition`;
+      return withHeaders(response, { Vary: merged });
+    }
+  }
+}