@mapled/next 0.11.0 → 0.11.1

package/README.md

@@ -390,6 +390,7 @@ export async function POST(req: Request) {
 ```
 
 - The route answers `{ release, publishedAt }` — the number of publishes and the time of the last one, nothing else — and may be cached by anyone. While Mapled can't be reached it keeps answering the last release it knew.
+- Refreshes ask your site, not the browser's cache. `router.refresh()` asks for the page's Server Components at the same URL every time, and a static page answers with `s-maxage` and `stale-while-revalidate` but no `max-age`: stale for the browser at once, which Chrome and Edge serve anyway while they fetch a fresh copy behind it. So from the first publish a tab hears about, every refresh of the page goes with `cache: "no-cache"`, and your site may still answer 304. That covers the component's own refresh, the one your `onPublish` makes (like the button above), and any your code makes. The layer changes only the cache mode, and only of requests your server reads as a refresh of the page the tab is on. Navigations, server actions, your own requests and any request that sets its own `cache` go as they did. A layer over `fetch`, put in place with the first publish, does it; a `fetch` wrapper of your own keeps working either way. (Before 0.11.1 an open tab showed the release before the one it was told about, from its second publish on.)
 - Expect a publish to reach an open tab in about ten seconds with the defaults. `<MapledLive interval={3} />` and `createReleaseHandler({ key, ttl: 1 })` make it quicker at the price of more requests to your site.
 - With a `basePath` in `next.config`, the route answers under it, and so does the default: `<MapledLive />` asks `/docs/api/mapled/release` on a site with `basePath: "/docs"` — Next writes the basePath into the bundle, and the component reads it from there (0.10.0 and later; earlier versions ask `/api/mapled/release`). An `endpoint` you pass is asked as written, basePath included: `<MapledLive endpoint="/docs/live" />`.
 - Leave route segment config off the release route: `createReleaseHandler` sets how it is cached. `dynamic = "force-static"` turns it into a copy Next builds without the tab's request, and `fetchCache = "force-no-store"` reads the release past the cache tag, so Mapled hears from the route every `ttl`. `dynamic = "force-dynamic"` does the same when the handler's `revalidate` is `false` or `0`; at its default it is harmless. On the webhook route, leave `fetchCache` off too: with `"force-no-store"` every answer names a new cache mark, and the release route may name no release. Middleware that runs on the route has to let the tab's `GET` through: no redirect, rewrite or sign-in wall. `output: "export"` has no server to run the route at all.

package/dist/live.js

@@ -22,6 +22,7 @@ export function MapledLive({ endpoint, interval, onPublish }) {
         endpoint,
         interval,
         onPublish: (next, previous) => {
+            refreshPastBrowserCache();
             if (custom.current)
                 custom.current(next, previous);
             else
@@ -30,3 +31,102 @@ export function MapledLive({ endpoint, interval, onPublish }) {
     }), [endpoint, interval, router]);
     return null;
 }
+/** The layers this module has put over `fetch`. */
+const layers = new WeakSet();
+/** Sends every refresh of the page from now on past the browser's cache:
+    ours, the one `onPublish` makes later, and one the site makes for its
+    own reasons alike — a request doesn't say whose it is, and a refresh
+    asks for fresh content anyway. A layer over `fetch` does it, put in
+    place when the first publish lands: Next asks `fetch` when it sends,
+    not when it loads. Code that wraps `fetch` later wraps the layer too;
+    code that puts back a `fetch` it kept from before gets a new layer
+    over it on the next publish. A layer, once there, stays: removing it
+    could take someone else's wrapper out with it.
+    The layer keeps nothing from one request to the next. A bypass armed
+    by each publish and spent by the first request that looked like the
+    refresh was spent, again and again, by prefetches it couldn't be told
+    from once a `fetch` wrapper had dropped their priority (PR 442). */
+function refreshPastBrowserCache() {
+    let below;
+    try {
+        below = globalThis.fetch;
+    }
+    catch {
+        return;
+    }
+    if (typeof below !== "function" || layers.has(below))
+        return;
+    const layer = function (input, init) {
+        return below.call(this, input, needsBypass(input, init) ? bypassing(init) : init);
+    };
+    layers.add(layer);
+    try {
+        globalThis.fetch = layer;
+    }
+    catch {
+        // a fetch that may not be replaced: the refresh goes as before
+    }
+}
+/** Whether a request is one the site's server reads as the router's
+    refresh of the page the tab is on, left to the browser's default
+    cache mode:
+    - a GET for the page's server components (the `rsc` header) that is
+      not a prefetch (no prefetch header);
+    - asked from the root of the router's tree: the `refetch` marker at
+      the root of `next-router-state-tree`, which `router.refresh()` sets
+      in Next 14, 15 and 16;
+    - to the tab's own address, the query compared less the `_rsc` Next
+      adds. Next 16 asks a route it doesn't know yet from the root too,
+      and `?page=2` of this page is another page here.
+    Only what the server reads decides, which a `fetch` wrapper can't
+    change without breaking the page — not the `priority` the browser
+    keeps, which a wrapper drops when it makes a `Request` of Next's
+    `(url, init)` or passes one on as fields. So Next 16's full prefetch
+    of this page, asked from the root while its segment cache is empty,
+    goes past the cache too: the server can't tell it from the refresh.
+    A cache mode someone chose (`no-store`, `reload`, `force-cache`) is
+    theirs, and it stays. */
+function needsBypass(input, init) {
+    try {
+        const request = typeof Request === "function" && input instanceof Request ? input : null;
+        if ((init?.cache ?? request?.cache ?? "default") !== "default")
+            return false;
+        const headers = new Headers(init?.headers ?? request?.headers);
+        const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+        if (method !== "GET" || headers.get("rsc") !== "1")
+            return false;
+        if (headers.has("next-router-prefetch") || headers.has("next-router-segment-prefetch"))
+            return false;
+        const tree = JSON.parse(decodeURIComponent(headers.get("next-router-state-tree") ?? ""));
+        if (!Array.isArray(tree) || tree[3] !== "refetch")
+            return false;
+        const url = new URL(request ? request.url : String(input), location.href);
+        return url.origin === location.origin && url.pathname === location.pathname && query(url.search) === query(location.search);
+    }
+    catch {
+        return false;
+    }
+}
+/** The members of `RequestInit`, which `fetch` reads with getters and
+    all: a spread copies only an object's own fields, and a `Request`
+    handed on as the init keeps its members on its prototype. */
+const MEMBERS = ["body", "cache", "credentials", "duplex", "headers", "integrity", "keepalive", "method", "mode", "priority", "redirect", "referrer", "referrerPolicy", "signal", "window"];
+/** `init` as `fetch` would read it, with `cache: "no-cache"` — the one
+    change the layer makes. */
+function bypassing(init) {
+    const read = { ...init };
+    for (const key of MEMBERS) {
+        const value = init?.[key];
+        if (value !== undefined)
+            read[key] = value;
+    }
+    read.cache = "no-cache";
+    return read;
+}
+/** A query as the page reads it: Next 14 writes the request's anew, 15
+    and 16 append `_rsc` to it as it was. */
+function query(search) {
+    const params = new URLSearchParams(search);
+    params.delete("_rsc");
+    return params.toString();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Read published Mapled content in a Next.js site \u2014 delivery client, ISR tags, and a revalidation webhook handler.",
   "license": "MIT",
   "homepage": "https://mapled.io",