@mapled/next 0.8.0 → 0.9.0

package/README.md

@@ -375,6 +375,38 @@ export function UpdateNotice() {
 
 Outside React, `watchRelease({ onPublish })` from `@mapled/next` is the same watch as a plain function — it returns the function that stops it.
 
+### Pages Router
+
+A site on `pages/` mounts the route as an API route and renders the component from `@mapled/next/live/pages` in its custom App:
+
+```ts
+// Pages Router: pages/api/mapled/release.ts
+import { createPagesReleaseHandler } from "@mapled/next/server";
+
+export default createPagesReleaseHandler({ key: process.env.MAPLED_KEY! });
+```
+
+```tsx
+// Pages Router: pages/_app.tsx
+import type { AppProps } from "next/app";
+import { MapledLive } from "@mapled/next/live/pages";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <>
+      <Component {...pageProps} />
+      <MapledLive />
+    </>
+  );
+}
+```
+
+On a publish it replaces the page with itself through `next/router`, so the page's data runs again and it re-renders with the new props in place: scroll position and client state stay. A `#hash` in the address goes: while there is one, a replace to the same page runs no data, and every render the router makes scrolls back to the hash's anchor. For the router it is a navigation to the same URL, so `routeChangeStart` and `routeChangeComplete` fire — a pageview counter listening to them counts it too. A publish that lands while the reader is on the way to another page, or to an anchor on this one, doesn't cancel that navigation: it waits for the page they land on and refreshes that one. The first check counts too: when the release it finds went live after the page was requested — a publish between `getServerSideProps` and that check, or while a tab opened in the background waited to be shown — the page refreshes, and `onPublish` gets `previous` as `null` (which release the page read, the tab can't tell). A page requested within ten seconds after a publish may refresh once for nothing. `endpoint`, `interval` and `onPublish` work as above. (`<MapledLive />` from `@mapled/next/live` would reload the whole tab here.)
+
+- **Pages that follow Publish read in `getServerSideProps`.** The Pages Router has no cache tag the route could share with a page, so `createPagesReleaseHandler` answers the live release as Mapled has it, and it moves the moment someone publishes. A page that reads in `getServerSideProps` reads that same release, so the refresh always renders the new content. Keep such a page out of shared caches — Next.js sends it uncached unless you set `Cache-Control` yourself.
+- A `getStaticProps` page can't keep up: it is a copy Next.js regenerates on its own schedule — when its `revalidate` window runs out, or when a webhook of yours calls `res.revalidate` — and the route can't wait for that. A tab that refreshes before the copy does gets the old copy back and won't hear of this publish again. Read the pages that should follow Publish in `getServerSideProps` instead.
+- Reads a page makes in the browser aren't part of its data: reload them in `onPublish`.
+
 ## Preview drafts
 
 Mount the preview routes:
@@ -509,6 +541,7 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
 - `createPreviewHandler({ apiUrl?, appUrl? })`, `createExitPreviewHandler()` — App Router `GET` handlers of the preview routes
 - `createReleaseHandler({ key, apiUrl?, ttl?, revalidate? })` — App Router `GET` handler of the release route; `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live` and `watchRelease({ endpoint?, interval?, onPublish })` ask it
+- `createPagesReleaseHandler({ key, apiUrl?, ttl? })` — Pages Router API route of the release route (the default export of `pages/api/mapled/release.ts`); `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live/pages` asks it
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
 
 The delivery key only reads published, public content — safe to use anywhere.

package/dist/live-pages.d.ts

@@ -0,0 +1,4 @@
+import type { MapledLiveProps } from "./live.js";
+export type { MapledLiveProps } from "./live.js";
+export type { Release } from "./watch.js";
+export declare function MapledLive({ endpoint, interval, onPublish }: MapledLiveProps): null;

package/dist/live-pages.js

@@ -0,0 +1,142 @@
+"use client";
+/** Open tabs of a Pages Router site follow Publish. Render it once, in
+    the custom App:
+
+    pages/_app.tsx:
+      import { MapledLive } from "@mapled/next/live/pages";
+      <><Component {...pageProps} /><MapledLive /></>
+
+    It asks the release route (`createPagesReleaseHandler` from
+    "@mapled/next/server", mounted at pages/api/mapled/release) every few
+    seconds and, when a publish lands, runs the page's data again through
+    the router, in place — scroll position and client state stay. A
+    module of its own, so an App Router bundle never pulls in
+    `next/router`, nor a Pages one `next/navigation`. */
+import { useRouter } from "next/router";
+import { useEffect, useRef } from "react";
+import { watchFrom } from "./watch.js";
+/** The Pages Router's way to re-run a page's data: a replace to where the
+    tab already is. Two details make it an actual refresh — the client
+    keeps `getStaticProps` data it fetched once, so its cache is skipped;
+    and while the address has a #hash, the router takes any replace to
+    the same path — with the hash or without it — for a hash change that
+    runs no data, and every render it makes scrolls back to the hash's
+    anchor. So the hash is left first, without scrolling, and stays gone:
+    putting it back would throw the reader back to the anchor. */
+function refresh(router) {
+    const at = router.asPath;
+    const cut = at.indexOf("#");
+    const path = cut === -1 ? at : at.slice(0, cut);
+    const run = () => router.replace(path, undefined, { scroll: false, unstable_skipClientCache: true });
+    (cut === -1
+        ? run()
+        : // false: another navigation took over — the tab is somewhere else now
+            router.replace(path, undefined, { scroll: false, shallow: true }).then((ok) => ok && run()))
+        // the router has reported it (routeChangeError), and a page it can't load it loads in full
+        .catch(() => false);
+}
+const landed = (trip, now) => !trip.moving && now !== trip.from;
+/** Mapled stamps a release when its publish starts, not when it commits
+    (a big one takes seconds), and its clock and the site's differ a
+    little: a release stamped up to this long before the page was asked
+    for may still be newer than what the page read. */
+const MARGIN_MS = 10_000;
+/** Whether `first` went live after this document was asked for — then
+    the page may have read the release before it: a publish between
+    getServerSideProps and the first check, or while a tab opened in the
+    background waited to be shown before asking. Compared on the servers'
+    clock, which the route's answer tells (`Date`, plus `Age` from a CDN),
+    so a browser whose clock is off changes nothing; an answer without
+    `Date` leaves the browser's own. Every error of the estimate — a
+    second's rounding in `Date`, the time the answer took to arrive —
+    makes a refresh likelier, never rarer; a page asked for within the
+    margin after a publish refreshes once for nothing. */
+function newerThanPage(first, headers) {
+    const askedAt = globalThis.performance?.timeOrigin;
+    if (askedAt === undefined)
+        return false;
+    const date = Date.parse(headers.get("date") ?? "");
+    const offset = Number.isNaN(date) ? 0 : date + (Number(headers.get("age")) || 0) * 1000 - Date.now();
+    return Date.parse(first.publishedAt) > askedAt + offset - MARGIN_MS;
+}
+export function MapledLive({ endpoint, interval, onPublish }) {
+    // the Pages Router hands out a new router object on every render: the
+    // watch reads the latest one and restarts only for a new route or pace
+    const router = useRouter();
+    const latest = useRef({ router, onPublish });
+    const trip = useRef({ moving: false, from: null, owed: false });
+    /** the newest release the page has started from or heard of — a watch
+        restarted for a new route or pace starts from it, not from the time */
+    const followed = useRef(undefined);
+    /** runs a refresh owed by a publish mid-navigation, once the page it
+        led to has rendered — the router's end-of-navigation event and
+        React's effect with the new router object come in either order */
+    const settle = () => {
+        const now = latest.current.router;
+        if (trip.current.owed && landed(trip.current, now)) {
+            trip.current.owed = false;
+            refresh(now);
+        }
+    };
+    useEffect(() => {
+        latest.current = { router, onPublish };
+        settle();
+    }, [router, onPublish]);
+    useEffect(() => {
+        const { events } = latest.current.router;
+        const start = () => {
+            trip.current.moving = true;
+            trip.current.from = latest.current.router;
+        };
+        const end = () => {
+            trip.current.moving = false;
+            settle();
+        };
+        // a cancelled navigation is not an end: what cancelled it is itself a
+        // navigation, which has started, or a hash change, or leaves the page
+        const failed = (err) => {
+            if (!err?.cancelled)
+                end();
+        };
+        // a jump to an anchor has no routeChangeStart, but the router awaits
+        // its render all the same
+        events.on("routeChangeStart", start);
+        events.on("hashChangeStart", start);
+        events.on("routeChangeComplete", end);
+        events.on("routeChangeError", failed);
+        events.on("hashChangeComplete", end);
+        return () => {
+            events.off("routeChangeStart", start);
+            events.off("hashChangeStart", start);
+            events.off("routeChangeComplete", end);
+            events.off("routeChangeError", failed);
+            events.off("hashChangeComplete", end);
+        };
+    }, []);
+    useEffect(() => watchFrom({
+        endpoint,
+        interval,
+        onPublish: (next, previous) => {
+            followed.current = next.release;
+            const { router: now, onPublish: custom } = latest.current;
+            if (custom)
+                custom(next, previous);
+            else if (!landed(trip.current, now))
+                trip.current.owed = true;
+            else {
+                trip.current.owed = false;
+                refresh(now);
+            }
+        },
+    }, 
+    // the first answer names what is live, not what the page read:
+    // one that went live after the page was asked for counts as a
+    // publish, with no `previous` — which release the page read, the
+    // tab can't tell
+    (first, headers) => {
+        const from = followed.current ?? (newerThanPage(first, headers) ? null : first.release);
+        followed.current = Math.max(first.release, followed.current ?? 0);
+        return from;
+    }), [endpoint, interval]);
+    return null;
+}

package/dist/server.d.ts

@@ -25,19 +25,42 @@ export declare function createRevalidateHandler(options: {
         client fetch. */
     tags?: string[];
 }): (req: Request) => Promise<Response>;
-/** GET handler for the release route (mount at /api/mapled/release):
-    the release this site serves right now, for `<MapledLive />` from
-    "@mapled/next/live" to ask about. The pointer is read under the
-    "mapled" tag like the content is, so it moves when the publish webhook
-    refreshes the cache and not before — a tab that refreshes on it
-    renders the new release, never the old one again. One answer is reused
-    for `ttl` seconds, in this instance and at the CDN in front of it:
-    however many tabs ask, Mapled hears from the site a few times a minute. */
-export declare function createReleaseHandler(options: {
+type ReleaseOptions = {
     key: string;
     apiUrl?: string;
     /** Seconds one answer is reused (default 5, at least 1). */
     ttl?: number;
+};
+/** GET handler for the release route of an App Router site (mount at
+    app/api/mapled/release/route.ts): the release this site serves right
+    now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
+    pointer is read under the "mapled" tag like the content is, so it
+    moves when the publish webhook refreshes the cache and not before — a
+    tab that refreshes on it renders the new release, never the old one
+    again. */
+export declare function createReleaseHandler(options: ReleaseOptions & {
     /** ISR window of the pointer, the same as a read's (default 3600 — the webhook keeps it fresh). */
     revalidate?: number | false;
 }): (req: Request) => Promise<Response>;
+/** What the Pages Router hands an API route: `NextApiRequest` and
+    `NextApiResponse` are these and more. */
+type PagesApiRequest = {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+};
+type PagesApiResponse = {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+};
+/** The release route of a Pages Router site — the default export of
+    pages/api/mapled/release.ts, for `<MapledLive />` from
+    "@mapled/next/live/pages" to ask about. The Pages Router has no cache
+    tag a route could share with a page, so the pointer is Mapled's live
+    release, read every `ttl` seconds: it moves the moment someone
+    publishes. A page that reads in `getServerSideProps` reads that same
+    release, and a tab refreshed on it renders the new content; a
+    `getStaticProps` page is a copy Next regenerates on its own schedule,
+    which the pointer can't wait for (README, «Live updates»). */
+export declare function createPagesReleaseHandler(options: ReleaseOptions): (req: PagesApiRequest, res: PagesApiResponse) => Promise<void>;
+export {};

package/dist/server.js

@@ -99,15 +99,13 @@ export function createRevalidateHandler(options) {
         return Response.json({ revalidated: true });
     };
 }
-/** GET handler for the release route (mount at /api/mapled/release):
-    the release this site serves right now, for `<MapledLive />` from
-    "@mapled/next/live" to ask about. The pointer is read under the
-    "mapled" tag like the content is, so it moves when the publish webhook
-    refreshes the cache and not before — a tab that refreshes on it
-    renders the new release, never the old one again. One answer is reused
-    for `ttl` seconds, in this instance and at the CDN in front of it:
-    however many tabs ask, Mapled hears from the site a few times a minute. */
-export function createReleaseHandler(options) {
+/** The release route, whichever router mounts it: one answer reused for
+    `ttl` seconds, in this instance and at the CDN in front of it —
+    however many tabs ask, Mapled hears from the site a few times a
+    minute. `next` is how the pointer is fetched: under the content's
+    cache tag in the App Router, as is in the Pages Router, which has no
+    such cache. */
+function releaseAnswers(options, next) {
     if (!options.key)
         throw new Error("Mapled: a delivery key is required.");
     const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
@@ -121,7 +119,7 @@ export function createReleaseHandler(options) {
         try {
             const init = {
                 headers: { "x-mapled-key": options.key },
-                next: { revalidate: options.revalidate ?? 3600, tags: ["mapled"] },
+                ...(next ? { next } : {}),
             };
             const res = await fetch(`${base}/v1/delivery/release`, init);
             if (!res.ok)
@@ -146,9 +144,8 @@ export function createReleaseHandler(options) {
             askedAt = Date.now();
         }
     }
-    return async function GET(req) {
-        // read first: a handler that looks at its request is never prerendered
-        const asked = req.headers.get("if-none-match");
+    /** `asked` — the tab's If-None-Match */
+    return async function answer(asked) {
         if (Date.now() - askedAt >= ttlMs) {
             loading ??= load().finally(() => {
                 loading = null;
@@ -156,15 +153,63 @@ export function createReleaseHandler(options) {
             await loading;
         }
         if (!held) {
-            return Response.json({ error: "The live release isn't available right now." }, { status: 502, headers: { "cache-control": "no-store" } });
+            return { status: 502, headers: { "cache-control": "no-store" }, body: { error: "The live release isn't available right now." } };
         }
         // the CDN's copy lives no longer than this instance's
         const left = Math.max(1, Math.ceil((ttlMs - (Date.now() - askedAt)) / 1000));
         const etag = `W/"r${held.release ?? 0}"`;
         const headers = { "cache-control": `public, max-age=0, s-maxage=${left}`, etag };
         if (asked && asked.split(",").some((t) => t.trim().replace(/^W\//, "") === etag.slice(2))) {
-            return new Response(null, { status: 304, headers });
+            return { status: 304, headers };
+        }
+        return { status: 200, headers, body: held };
+    };
+}
+/** GET handler for the release route of an App Router site (mount at
+    app/api/mapled/release/route.ts): the release this site serves right
+    now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
+    pointer is read under the "mapled" tag like the content is, so it
+    moves when the publish webhook refreshes the cache and not before — a
+    tab that refreshes on it renders the new release, never the old one
+    again. */
+export function createReleaseHandler(options) {
+    const answer = releaseAnswers(options, { revalidate: options.revalidate ?? 3600, tags: ["mapled"] });
+    return async function GET(req) {
+        // read first: a handler that looks at its request is never prerendered
+        const { status, headers, body } = await answer(req.headers.get("if-none-match"));
+        return status === 304 ? new Response(null, { status, headers }) : Response.json(body, { status, headers });
+    };
+}
+/** The release route of a Pages Router site — the default export of
+    pages/api/mapled/release.ts, for `<MapledLive />` from
+    "@mapled/next/live/pages" to ask about. The Pages Router has no cache
+    tag a route could share with a page, so the pointer is Mapled's live
+    release, read every `ttl` seconds: it moves the moment someone
+    publishes. A page that reads in `getServerSideProps` reads that same
+    release, and a tab refreshed on it renders the new content; a
+    `getStaticProps` page is a copy Next regenerates on its own schedule,
+    which the pointer can't wait for (README, «Live updates»). */
+export function createPagesReleaseHandler(options) {
+    const answer = releaseAnswers(options);
+    return async function handler(req, res) {
+        const method = req.method ?? "GET";
+        if (method !== "GET" && method !== "HEAD") {
+            res.statusCode = 405;
+            res.setHeader("allow", "GET, HEAD");
+            res.end();
+            return;
+        }
+        const asked = req.headers["if-none-match"];
+        const { status, headers, body } = await answer(Array.isArray(asked) ? asked.join(",") : (asked ?? null));
+        res.statusCode = status;
+        for (const [name, value] of Object.entries(headers))
+            res.setHeader(name, value);
+        if (body === undefined) {
+            res.end();
+            return;
         }
-        return Response.json(held, { headers });
+        // written as is: res.json would swap the ETag for a hash of the body
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(method === "HEAD" ? undefined : JSON.stringify(body));
     };
 }

package/dist/watch.d.ts

@@ -21,3 +21,10 @@ export type WatchOptions = {
     comes after it. A hidden tab doesn't ask — it checks the moment it is
     shown again — and a route that fails is asked less and less often. */
 export declare function watchRelease(options: WatchOptions): () => void;
+/** The watch behind `watchRelease`, for a caller that can tell more about
+    where to start than the first answer can. `from` gets the first
+    release the route names, with the answer's headers, and returns the
+    release the page is on — the first answer's own number to start from
+    it, an older one (or null: not known) to hand the first answer to
+    `onPublish` as well. Not part of the package's API. */
+export declare function watchFrom(options: WatchOptions, from?: (first: Release, headers: Headers) => number | null): () => void;

package/dist/watch.js

@@ -22,6 +22,15 @@ function pointer(body) {
     comes after it. A hidden tab doesn't ask — it checks the moment it is
     shown again — and a route that fails is asked less and less often. */
 export function watchRelease(options) {
+    return watchFrom(options);
+}
+/** The watch behind `watchRelease`, for a caller that can tell more about
+    where to start than the first answer can. `from` gets the first
+    release the route names, with the answer's headers, and returns the
+    release the page is on — the first answer's own number to start from
+    it, an older one (or null: not known) to hand the first answer to
+    `onPublish` as well. Not part of the package's API. */
+export function watchFrom(options, from) {
     const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
     const everyMs = Math.max(2, options.interval ?? 10) * 1000;
     const doc = typeof document === "undefined" ? null : document;
@@ -54,10 +63,9 @@ export function watchRelease(options) {
             }
             else {
                 failures = 0;
-                if (seen === undefined) {
-                    seen = now ? now.release : null;
-                }
-                else if (now && now.release > (seen ?? 0)) {
+                if (seen === undefined)
+                    seen = now ? (from ? from(now, res.headers) : now.release) : null;
+                if (now && now.release > (seen ?? 0)) {
                     // releases only grow (a rollback is a new one): an answer from a
                     // server that hasn't caught up yet never looks like news
                     news = { next: now, previous: seen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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",
@@ -31,6 +31,10 @@
     "./live": {
       "types": "./dist/live.d.ts",
       "default": "./dist/live.js"
+    },
+    "./live/pages": {
+      "types": "./dist/live-pages.d.ts",
+      "default": "./dist/live-pages.js"
     }
   },
   "files": [