cdk-nextjs 0.6.1 → 0.7.0

package/lib/adapter/adapter.test.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable import/no-extraneous-dependencies */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const esbuild_1 = require("esbuild");
+// `adapter.mts` is ESM that calls `import.meta.resolve`, which ts-jest's
+// CommonJS cannot run, so it is bundled the way `pnpm bundle` does and driven
+// from a real `node`. Its `cdk-nextjs/…` specifiers resolve against a stand-in
+// package carrying the real `exports`, so the test needs no prior bundle.
+const repoRoot = (0, node_path_1.join)(__dirname, "..", "..");
+let dir;
+let pkgDir;
+beforeAll(() => {
+    // Real, since `import.meta.resolve` returns real paths (macOS's tmpdir is a link).
+    dir = (0, node_fs_1.realpathSync)((0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "cdk-nextjs-adapter-")));
+    pkgDir = (0, node_path_1.join)(dir, "node_modules", "cdk-nextjs");
+    const { exports } = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, "package.json"), "utf-8"));
+    (0, node_fs_1.mkdirSync)(pkgDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(pkgDir, "package.json"), JSON.stringify({ name: "cdk-nextjs", exports }));
+    for (const target of Object.values(exports)) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)((0, node_path_1.join)(pkgDir, target.import)), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(pkgDir, target.import), "");
+    }
+    (0, node_fs_1.symlinkSync)((0, node_path_1.join)(repoRoot, "node_modules", "next"), (0, node_path_1.join)(dir, "node_modules", "next"));
+    (0, esbuild_1.buildSync)({
+        entryPoints: [(0, node_path_1.join)(repoRoot, "src/adapter/adapter.mts")],
+        bundle: true,
+        platform: "node",
+        target: "node24",
+        format: "esm",
+        external: ["next"],
+        outfile: (0, node_path_1.join)(dir, "adapter.mjs"),
+        banner: {
+            js: "import { createRequire as __cdkNextjsCreateRequire } from 'node:module'; const require = __cdkNextjsCreateRequire(import.meta.url);",
+        },
+        logLevel: "silent",
+    });
+});
+afterAll(() => {
+    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+});
+/** `adapter.modifyConfig(config, { phase, nextVersion })`, run by `node`. */
+function modifyConfig(config, phase, nextVersion = "16.3.0") {
+    const script = `import adapter from ${JSON.stringify((0, node_path_1.join)(dir, "adapter.mjs"))};` +
+        `const out = await adapter.modifyConfig(${JSON.stringify(config)}, ` +
+        `${JSON.stringify({ phase, nextVersion })});` +
+        `process.stdout.write(JSON.stringify(out));`;
+    return JSON.parse((0, node_child_process_1.execFileSync)(process.execPath, ["--input-type=module", "-e", script], {
+        cwd: dir,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    }));
+}
+const handler = (path) => (0, node_path_1.join)(pkgDir, "lib/adapter", path);
+const ours = () => ({
+    default: handler("use-cache-default-handler.mjs"),
+    remote: handler("use-cache-remote-handler.mjs"),
+});
+describe("modifyConfig", () => {
+    it("wires cdk-nextjs's cache handlers into the build", () => {
+        const out = modifyConfig({ images: {} }, "phase-production-build");
+        expect(out.cacheHandler).toBe(handler("cache-handler.mjs"));
+        expect(out.cacheHandlers).toEqual(ours());
+        expect(out.images.customCacheHandler).toBe(true);
+    });
+    it("keeps the handlers the app configured, and adds the missing ones", () => {
+        const out = modifyConfig({
+            cacheHandler: "/app/my-handler.js",
+            cacheHandlers: { remote: "/app/remote.js", custom: "/app/custom.js" },
+            images: { customCacheHandler: "/app/images.js" },
+        }, "phase-production-build");
+        expect(out.cacheHandler).toBe("/app/my-handler.js");
+        expect(out.cacheHandlers).toEqual({
+            default: ours().default,
+            remote: "/app/remote.js",
+            custom: "/app/custom.js",
+        });
+        expect(out.images.customCacheHandler).toBe("/app/images.js");
+    });
+    // `next start` registers `use cache` handlers from this config, once.
+    it("registers the same `use cache` handlers for `next start`", () => {
+        const out = modifyConfig({ cacheHandlers: { default: "/app/default.js" } }, "phase-production-server");
+        expect(out.cacheHandlers).toEqual({
+            default: "/app/default.js",
+            remote: ours().remote,
+        });
+        expect(out.cacheHandler).toBeUndefined();
+    });
+    it("leaves other phases alone", () => {
+        expect(modifyConfig({ images: {} }, "phase-development-server")).toEqual({
+            images: {},
+        });
+    });
+});
+describe("assertSupportedNextVersion", () => {
+    it.each(["16.2.9", "15.5.0"])("rejects Next.js %s at build time", (version) => {
+        expect(() => modifyConfig({ images: {} }, "phase-production-build", version)).toThrow(`Next.js ${version} is not supported`);
+    });
+    it.each(["16.3.0", "17.0.0-canary.1"])("accepts Next.js %s", (version) => {
+        expect(() => modifyConfig({ images: {} }, "phase-production-build", version)).not.toThrow();
+    });
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWRhcHRlci50ZXN0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FkYXB0ZXIvYWRhcHRlci50ZXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBQUEsc0RBQXNEO0FBQ3RELDJEQUFrRDtBQUNsRCxxQ0FRaUI7QUFDakIscUNBQWlDO0FBQ2pDLHlDQUEwQztBQUMxQyxxQ0FBb0M7QUFFcEMseUVBQXlFO0FBQ3pFLDhFQUE4RTtBQUM5RSwrRUFBK0U7QUFDL0UsMEVBQTBFO0FBQzFFLE1BQU0sUUFBUSxHQUFHLElBQUEsZ0JBQUksRUFBQyxTQUFTLEVBQUUsSUFBSSxFQUFFLElBQUksQ0FBQyxDQUFDO0FBQzdDLElBQUksR0FBVyxDQUFDO0FBQ2hCLElBQUksTUFBYyxDQUFDO0FBRW5CLFNBQVMsQ0FBQyxHQUFHLEVBQUU7SUFDYixtRkFBbUY7SUFDbkYsR0FBRyxHQUFHLElBQUEsc0JBQVksRUFBQyxJQUFBLHFCQUFXLEVBQUMsSUFBQSxnQkFBSSxFQUFDLElBQUEsZ0JBQU0sR0FBRSxFQUFFLHFCQUFxQixDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3ZFLE1BQU0sR0FBRyxJQUFBLGdCQUFJLEVBQUMsR0FBRyxFQUFFLGNBQWMsRUFBRSxZQUFZLENBQUMsQ0FBQztJQUNqRCxNQUFNLEVBQUUsT0FBTyxFQUFFLEdBQUcsSUFBSSxDQUFDLEtBQUssQ0FDNUIsSUFBQSxzQkFBWSxFQUFDLElBQUEsZ0JBQUksRUFBQyxRQUFRLEVBQUUsY0FBYyxDQUFDLEVBQUUsT0FBTyxDQUFDLENBQ3RELENBQUM7SUFDRixJQUFBLG1CQUFTLEVBQUMsTUFBTSxFQUFFLEVBQUUsU0FBUyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7SUFDdkMsSUFBQSx1QkFBYSxFQUNYLElBQUEsZ0JBQUksRUFBQyxNQUFNLEVBQUUsY0FBYyxDQUFDLEVBQzVCLElBQUksQ0FBQyxTQUFTLENBQUMsRUFBRSxJQUFJLEVBQUUsWUFBWSxFQUFFLE9BQU8sRUFB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QUNWLFlBQVksQ0FBQyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsRUFBRSx3QkFBd0IsRUFBRSxPQUFPLENBQUMsQ0FDaEUsQ0FBQyxHQUFHLENBQUMsT0FBTyxFQUFFLENBQUM7SUFDbEIsQ0FBQyxDQUFDLENBQUM7QUFDTCxDQUFDLENBQUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qIGVzbGludC1kaXNhYmxlIGltcG9ydC9uby1leHRyYW5lb3VzLWRlcGVuZGVuY2llcyAqL1xuaW1wb3J0IHsgZXhlY0ZpbGVTeW5jIH0gZnJvbSBcIm5vZGU6Y2hpbGRfcHJvY2Vzc1wiO1xuaW1wb3J0IHtcbiAgbWtkaXJTeW5jLFxuICBta2R0ZW1wU3luYyxcbiAgcmVhZEZpbGVTeW5jLFxuICByZWFscGF0aFN5bmMsXG4gIHJtU3luYyxcbiAgc3ltbGlua1N5bmMsXG4gIHdyaXRlRmlsZVN5bmMsXG59IGZyb20gXCJub2RlOmZzXCI7XG5pbXBvcnQgeyB0bXBkaXIgfSBmcm9tIFwibm9kZTpvc1wiO1xuaW1wb3J0IHsgZGlybmFtZSwgam9pbiB9IGZyb20gXCJub2RlOnBhdGhcIjtcbmltcG9ydCB7IGJ1aWxkU3luYyB9IGZyb20gXCJlc2J1aWxkXCI7XG5cbi8vIGBhZGFwdGVyLm10c2AgaXMgRVNNIHRoYXQgY2FsbHMgYGltcG9ydC5tZXRhLnJlc29sdmVgLCB3aGljaCB0cy1qZXN0J3Ncbi8vIENvbW1vbkpTIGNhbm5vdCBydW4sIHNvIGl0IGlzIGJ1bmRsZWQgdGhlIHdheSBgcG5wbSBidW5kbGVgIGRvZXMgYW5kIGRyaXZlblxuLy8gZnJvbSBhIHJlYWwgYG5vZGVgLiBJdHMgYGNkay1uZXh0anMv4oCmYCBzcGVjaWZpZXJzIHJlc29sdmUgYWdhaW5zdCBhIHN0YW5kLWluXG4vLyBwYWNrYWdlIGNhcnJ5aW5nIHRoZSByZWFsIGBleHBvcnRzYCwgc28gdGhlIHRlc3QgbmVlZHMgbm8gcHJpb3IgYnVuZGxlLlxuY29uc3QgcmVwb1Jvb3QgPSBqb2luKF9fZGlybmFtZSwgXCIuLlwiLCBcIi4uXCIpO1xubGV0IGRpcjogc3RyaW5nO1xubGV0IHBrZ0Rpcjogc3RyaW5nO1xuXG5iZWZvcmVBbGwoKCkgPT4ge1xuICAvLyBSZWFsLCBzaW5jZSBgaW1wb3J0Lm1ldGEucmVzb2x2ZWAgcmV0dXJucyByZWFsIHBhdGhzIChtYWNPUydzIHRtcGRpciBpcyBhIGxpbmspLlxuICBkaXIgPSByZWFscGF0aFN5bmMobWtkdGVtcFN5bmMoam9pbih0bXBkaXIoKSwgXCJjZGstbmV4dGpzLWFkYXB0ZXItXCIpKSk7XG4gIHBrZ0RpciA9IGpvaW4oZGlyLCBcIm5vZGVfbW9kdWxlc1wiLCBcImNkay1uZXh0anNcIik7XG4gIGNvbnN0IHsgZXhwb3J0cyB9ID0gSlNPTi5wYXJzZShcbiAgICByZWFkRmlsZVN5bmMoam9pbihyZXBvUm9vdCwgXCJwYWNrYWdlLmpzb25cIiksIFwidXRmLThcIiksXG4gICk7XG4gIG1rZGlyU3luYyhwa2dEaXIsIHsgcmVjdXJzaXZlOiB0cnVlIH0pO1xuICB3cml0ZUZpbGVTeW5jKFxuICAgIGpvaW4ocGtnRGlyLCBcInBhY2thZ2UuanNvblwiKSxcbiAgICBKU09OLnN0cmluZ2lmeSh7IG5hbWU6IFwiY2RrLW5leHRqc1wiLCBleHBvcnRzIH0pLFxuICApO1xuICBmb3IgKGNvbnN0IHRhcmdldCBvZiBPYmplY3QudmFsdWVzKGV4cG9ydHMpIGFzIHsgaW1wb3J0OiBzdHJpbmcgfVtdKSB7XG4gICAgbWtkaXJTeW5jKGRpcm5hbWUoam9pbihwa2dEaXIsIHRhcmdldC5pbXBvcnQpKSwgeyByZWN1cnNpdmU6IHRydWUgfSk7XG4gICAgd3JpdGVGaWxlU3luYyhqb2luKHBrZ0RpciwgdGFyZ2V0LmltcG9ydCksIFwiXCIpO1xuICB9XG4gIHN5bWxpbmtTeW5jKFxuICAgIGpvaW4ocmVwb1Jvb3QsIFwibm9kZV9tb2R1bGVzXCIsIFwibmV4dFwiKSxcbiAgICBqb2luKGRpciwgXCJub2RlX21vZHVsZXNcIiwgXCJuZXh0XCIpLFxuICApO1xuICBidWlsZFN5bmMoe1xuICAgIGVudHJ5UG9pbnRzOiBbam9pbihyZXBvUm9vdCwgXCJzcmMvYWRhcHRlci9hZGFwdGVyLm10c1wiKV0sXG4gICAgYnVuZGxlOiB0cnVlLFxuICAgIHBsYXRmb3JtOiBcIm5vZGVcIixcbiAgICB0YXJnZXQ6IFwibm9kZTI0XCIsXG4gICAgZm9ybWF0OiBcImVzbVwiLFxuICAgIGV4dGVybmFsOiBbXCJuZXh0XCJdLFxuICAgIG91dGZpbGU6IGpvaW4oZGlyLCBcImFkYXB0ZXIubWpzXCIpLFxuICAgIGJhbm5lcjoge1xuICAgICAganM6IFwiaW1wb3J0IHsgY3JlYXRlUmVxdWlyZSBhcyBfX2Nka05leHRqc0NyZWF0ZVJlcXVpcmUgfSBmcm9tICdub2RlOm1vZHVsZSc7IGNvbnN0IHJlcXVpcmUgPSBfX2Nka05leHRqc0NyZWF0ZVJlcXVpcmUoaW1wb3J0Lm1ldGEudXJsKTtcIixcbiAgICB9LFxuICAgIGxvZ0xldmVsOiBcInNpbGVudFwiLFxuICB9KTtcbn0pO1xuXG5hZnRlckFsbCgoKSA9PiB7XG4gIHJtU3luYyhkaXIsIHsgcmVjdXJzaXZlOiB0cnVlLCBmb3JjZTogdHJ1ZSB9KTtcbn0pO1xuXG4vKiogYGFkYXB0ZXIubW9kaWZ5Q29uZmlnKGNvbmZpZywgeyBwaGFzZSwgbmV4dFZlcnNpb24gfSlgLCBydW4gYnkgYG5vZGVgLiAqL1xuZnVuY3Rpb24gbW9kaWZ5Q29uZmlnKFxuICBjb25maWc6IFJlY29yZDxzdHJpbmcsIHVua25vd24+LFxuICBwaGFzZTogc3RyaW5nLFxuICBuZXh0VmVyc2lvbiA9IFwiMTYuMy4wXCIsXG4pOiBSZWNvcmQ8c3RyaW5nLCBhbnk+IHtcbiAgY29uc3Qgc2NyaXB0ID1cbiAgICBgaW1wb3J0IGFkYXB0ZXIgZnJvbSAke0pTT04uc3RyaW5naWZ5KGpvaW4oZGlyLCBcImFkYXB0ZXIubWpzXCIpKX07YCArXG4gICAgYGNvbnN0IG91dCA9IGF3YWl0IGFkYXB0ZXIubW9kaWZ5Q29uZmlnKCR7SlNPTi5zdHJpbmdpZnkoY29uZmlnKX0sIGAgK1xuICAgIGAke0pTT04uc3RyaW5naWZ5KHsgcGhhc2UsIG5leHRWZXJzaW9uIH0pfSk7YCArXG4gICAgYHByb2Nlc3Muc3Rkb3V0LndyaXRlKEpTT04uc3RyaW5naWZ5KG91dCkpO2A7XG4gIHJldHVybiBKU09OLnBhcnNlKFxuICAgIGV4ZWNGaWxlU3luYyhwcm9jZXNzLmV4ZWNQYXRoLCBbXCItLWlucHV0LXR5cGU9bW9kdWxlXCIsIFwiLWVcIiwgc2NyaXB0XSwge1xuICAgICAgY3dkOiBkaXIsXG4gICAgICBlbmNvZGluZzogXCJ1dGYtOFwiLFxuICAgICAgc3RkaW86IFtcImlnbm9yZVwiLCBcInBpcGVcIiwgXCJwaXBlXCJdLFxuICAgIH0pLFxuICApO1xufVxuXG5jb25zdCBoYW5kbGVyID0gKHBhdGg6IHN0cmluZykgPT4gam9pbihwa2dEaXIsIFwibGliL2FkYXB0ZXJcIiwgcGF0aCk7XG5jb25zdCBvdXJzID0gKCkgPT4gKHtcbiAgZGVmYXVsdDogaGFuZGxlcihcInVzZS1jYWNoZS1kZWZhdWx0LWhhbmRsZXIubWpzXCIpLFxuICByZW1vdGU6IGhhbmRsZXIoXCJ1c2UtY2FjaGUtcmVtb3RlLWhhbmRsZXIubWpzXCIpLFxufSk7XG5cbmRlc2NyaWJlKFwibW9kaWZ5Q29uZmlnXCIsICgpID0+IHtcbiAgaXQoXCJ3aXJlcyBjZGstbmV4dGpzJ3MgY2FjaGUgaGFuZGxlcnMgaW50byB0aGUgYnVpbGRcIiwgKCkgPT4ge1xuICAgIGNvbnN0IG91dCA9IG1vZGlmeUNvbmZpZyh7IGltYWdlczoge30gfSwgXCJwaGFzZS1wcm9kdWN0aW9uLWJ1aWxkXCIpO1xuICAgIGV4cGVjdChvdXQuY2FjaGVIYW5kbGVyKS50b0JlKGhhbmRsZXIoXCJjYWNoZS1oYW5kbGVyLm1qc1wiKSk7XG4gICAgZXhwZWN0KG91dC5jYWNoZUhhbmRsZXJzKS50b0VxdWFsKG91cnMoKSk7XG4gICAgZXhwZWN0KG91dC5pbWFnZXMuY3VzdG9tQ2FjaGVIYW5kbGVyKS50b0JlKHRydWUpO1xuICB9KTtcblxuICBpdChcImtlZXBzIHRoZSBoYW5kbGVycyB0aGUgYXBwIGNvbmZpZ3VyZWQsIGFuZCBhZGRzIHRoZSBtaXNzaW5nIG9uZXNcIiwgKCkgPT4ge1xuICAgIGNvbnN0IG91dCA9IG1vZGlmeUNvbmZpZyhcbiAgICAgIHtcbiAgICAgICAgY2FjaGVIYW5kbGVyOiBcIi9hcHAvbXktaGFuZGxlci5qc1wiLFxuICAgICAgICBjYWNoZUhhbmRsZXJzOiB7IHJlbW90ZTogXCIvYXBwL3JlbW90ZS5qc1wiLCBjdXN0b206IFwiL2FwcC9jdXN0b20uanNcIiB9LFxuICAgICAgICBpbWFnZXM6IHsgY3VzdG9tQ2FjaGVIYW5kbGVyOiBcIi9hcHAvaW1hZ2VzLmpzXCIgfSxcbiAgICAgIH0sXG4gICAgICBcInBoYXNlLXByb2R1Y3Rpb24tYnVpbGRcIixcbiAgICApO1xuICAgIGV4cGVjdChvdXQuY2FjaGVIYW5kbGVyKS50b0JlKFwiL2FwcC9teS1oYW5kbGVyLmpzXCIpO1xuICAgIGV4cGVjdChvdXQuY2FjaGVIYW5kbGVycykudG9FcXVhbCh7XG4gICAgICBkZWZhdWx0OiBvdXJzKCkuZGVmYXVsdCxcbiAgICAgIHJlbW90ZTogXCIvYXBwL3JlbW90ZS5qc1wiLFxuICAgICAgY3VzdG9tOiBcIi9hcHAvY3VzdG9tLmpzXCIsXG4gICAgfSk7XG4gICAgZXhwZWN0KG91dC5pbWFnZXMuY3VzdG9tQ2FjaGVIYW5kbGVyKS50b0JlKFwiL2FwcC9pbWFnZXMuanNcIik7XG4gIH0pO1xuXG4gIC8vIGBuZXh0IHN0YXJ0YCByZWdpc3RlcnMgYHVzZSBjYWNoZWAgaGFuZGxlcnMgZnJvbSB0aGlzIGNvbmZpZywgb25jZS5cbiAgaXQoXCJyZWdpc3RlcnMgdGhlIHNhbWUgYHVzZSBjYWNoZWAgaGFuZGxlcnMgZm9yIGBuZXh0IHN0YXJ0YFwiLCAoKSA9PiB7XG4gICAgY29uc3Qgb3V0ID0gbW9kaWZ5Q29uZmlnKFxuICAgICAgeyBjYWNoZUhhbmRsZXJzOiB7IGRlZmF1bHQ6IFwiL2FwcC9kZWZhdWx0LmpzXCIgfSB9LFxuICAgICAgXCJwaGFzZS1wcm9kdWN0aW9uLXNlcnZlclwiLFxuICAgICk7XG4gICAgZXhwZWN0KG91dC5jYWNoZUhhbmRsZXJzKS50b0VxdWFsKHtcbiAgICAgIGRlZmF1bHQ6IFwiL2FwcC9kZWZhdWx0LmpzXCIsXG4gICAgICByZW1vdGU6IG91cnMoKS5yZW1vdGUsXG4gICAgfSk7XG4gICAgZXhwZWN0KG91dC5jYWNoZUhhbmRsZXIpLnRvQmVVbmRlZmluZWQoKTtcbiAgfSk7XG5cbiAgaXQoXCJsZWF2ZXMgb3RoZXIgcGhhc2VzIGFsb25lXCIsICgpID0+IHtcbiAgICBleHBlY3QobW9kaWZ5Q29uZmlnKHsgaW1hZ2VzOiB7fSB9LCBcInBoYXNlLWRldmVsb3BtZW50LXNlcnZlclwiKSkudG9FcXVhbCh7XG4gICAgICBpbWFnZXM6IHt9LFxuICAgIH0pO1xuICB9KTtcbn0pO1xuXG5kZXNjcmliZShcImFzc2VydFN1cHBvcnRlZE5leHRWZXJzaW9uXCIsICgpID0+IHtcbiAgaXQuZWFjaChbXCIxNi4yLjlcIiwgXCIxNS41LjBcIl0pKFxuICAgIFwicmVqZWN0cyBOZXh0LmpzICVzIGF0IGJ1aWxkIHRpbWVcIixcbiAgICAodmVyc2lvbikgPT4ge1xuICAgICAgZXhwZWN0KCgpID0+XG4gICAgICAgIG1vZGlmeUNvbmZpZyh7IGltYWdlczoge30gfSwgXCJwaGFzZS1wcm9kdWN0aW9uLWJ1aWxkXCIsIHZlcnNpb24pLFxuICAgICAgKS50b1Rocm93KGBOZXh0LmpzICR7dmVyc2lvbn0gaXMgbm90IHN1cHBvcnRlZGApO1xuICAgIH0sXG4gICk7XG5cbiAgaXQuZWFjaChbXCIxNi4zLjBcIiwgXCIxNy4wLjAtY2FuYXJ5LjFcIl0pKFwiYWNjZXB0cyBOZXh0LmpzICVzXCIsICh2ZXJzaW9uKSA9PiB7XG4gICAgZXhwZWN0KCgpID0+XG4gICAgICBtb2RpZnlDb25maWcoeyBpbWFnZXM6IHt9IH0sIFwicGhhc2UtcHJvZHVjdGlvbi1idWlsZFwiLCB2ZXJzaW9uKSxcbiAgICApLm5vdC50b1Rocm93KCk7XG4gIH0pO1xufSk7XG4iXX0=

package/lib/adapter/aws-cache-store.d.ts

@@ -0,0 +1,489 @@
+import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
+import { S3Client } from "@aws-sdk/client-s3";
+/**
+ * Where the cache lives, as the constructs pass it to the compute through the
+ * environment (`NextjsFunctions`, `NextjsContainers`). Empty strings for what is
+ * not configured, which each handler reads as "that layer is disabled".
+ */
+export interface AwsCacheConfig {
+    /** `CDK_NEXTJS_CACHE_BUCKET_NAME`. */
+    bucketName: string;
+    /** `CDK_NEXTJS_REVALIDATION_TABLE_NAME`. */
+    tableName: string;
+    /** `AWS_REGION`, `us-east-1` when unset. */
+    region: string;
+    /** `CDK_NEXTJS_BUILD_ID`: every S3 key and every marker row is scoped to it. */
+    buildId: string;
+}
+/** The configuration from the environment. */
+export declare function resolveAwsCacheConfig(): AwsCacheConfig;
+/**
+ * `{buildId}/{cacheKey}.json`, the incremental cache's key convention.
+ *
+ * The root path becomes `index`, and a leading slash is dropped so there is no
+ * empty folder under the build prefix. Everything this returns ends in `.json`,
+ * which is what keeps it disjoint from {@link useCacheS3Key}.
+ */
+export declare function buildS3Key(buildId: string, cacheKey: string): string;
+/**
+ * The folder under the build prefix that `'use cache'` entries are stored in.
+ * @see useCacheS3Key
+ */
+export declare const USE_CACHE_KEY_PREFIX = "_use-cache";
+/**
+ * `{buildId}/_use-cache/{hash}.entry`, where a `cacheHandlers` entry is stored.
+ *
+ * Hashed because a `'use cache'` key is the serialized arguments of the call and
+ * has no length limit, where an S3 key stops at 1024 bytes. The `.entry` suffix
+ * rather than `.json` is what makes a collision with the incremental cache
+ * impossible rather than unlikely: every key {@link buildS3Key} writes ends in
+ * `.json`, including one for a route that happens to be named `/_use-cache/…`.
+ * Still under the build prefix, so post-deploy pruning drops them with the build.
+ */
+export declare function useCacheS3Key(buildId: string, keyHash: string): string;
+/**
+ * The `durations` Next.js 16 passes a tag revalidation for a profile:
+ * `revalidateTag("posts", "max")` arrives as `{ expire: <the profile's expire> }`.
+ * Absent for `updateTag` and a bare `revalidateTag`, which expire immediately.
+ */
+export interface RevalidateDurations {
+    expire?: number;
+}
+/**
+ * A tag's marker row, as timestamps in milliseconds. Written by
+ * {@link markerUpdate}; each field is absent until a revalidation of that shape
+ * has happened.
+ */
+export interface TagMarker {
+    /** Expired outright: `updateTag`, or `revalidateTag` with no profile. */
+    revalidatedAt?: number;
+    /** Stale from here: `revalidateTag(tag, profile)`. */
+    staleAt?: number;
+    /** When the profile's `expire` runs out, which may be in the future. */
+    expiredAt?: number;
+}
+/**
+ * What the tag markers say about an entry: untouched, served stale while a
+ * background render replaces it, or expired and re-rendered before answering.
+ */
+export type RevalidationState = "fresh" | "stale" | "expired";
+/**
+ * What `marker` means for an entry created at `createdAt`, at `now`.
+ *
+ * `expiredAt` in the future is a profile's `expire` that has not come yet,
+ * compared the way Next.js's `areTagsExpired` does.
+ */
+export declare function markerState(marker: TagMarker, createdAt: number, now: number): RevalidationState;
+/**
+ * The clock every tag marker is stamped with, and every entry timestamp it is
+ * compared against: the one Next.js stamps `CacheEntry.timestamp` with
+ * (`performance.timeOrigin + performance.now()`, in `use-cache-wrapper.js` and
+ * the default handler), rather than `Date.now()`. Both handlers write the same
+ * marker rows, so both have to use it: two clocks on one row let the last writer
+ * decide which clock the others compare against, and they drift apart for as
+ * long as a Lambda sandbox or Fargate task lives.
+ */
+export declare function markerClock(): number;
+/**
+ * The marker fields a tag revalidated at `now` sets.
+ *
+ * Without `durations` - `updateTag`, or `revalidateTag` with no profile - the
+ * tag's entries expire immediately (`revalidatedAt`). With them the entries go
+ * stale now and expire after the profile's `expire`, the same pair of
+ * timestamps Next.js's `FileSystemCache.revalidateTag` records. A profile with
+ * no `expire` sets only `staleAt`, and whatever `expiredAt` the tag had stays.
+ */
+export declare function markerFor(now: number, durations: RevalidateDurations | undefined): TagMarker;
+/**
+ * `existing` with the fields `update` sets, as a {@link markerUpdate} leaves
+ * the row: a field `update` does not set keeps its value.
+ */
+export declare function applyMarker(existing: TagMarker | undefined, update: TagMarker): TagMarker;
+/** The marker-row update that sets {@link markerFor}'s fields. */
+export declare function markerUpdate(now: number, durations: RevalidateDurations | undefined): Pick<ConstructorParameters<typeof UpdateItemCommand>[0], "UpdateExpression" | "ExpressionAttributeValues">;
+/** DynamoDB's cap on keys in one `BatchGetItem`. */
+export declare const BATCH_GET_MAX_KEYS = 100;
+/**
+ * How often, at most, an instance catches up on revalidations other instances
+ * ran, unless `CDK_NEXTJS_TAG_REFRESH_MS` says otherwise: the staleness window
+ * for a `revalidateTag` run elsewhere. Every cache hit checks its tags'
+ * markers, and every marker of a deployment shares one partition key, so
+ * reading them per request capped a route's cache hits at the partition's read
+ * throughput (~1,900 req/s on NextjsRegionalFunctions). Once a second, from the
+ * revalidation log, the reads scale with instances instead of requests or tags.
+ */
+export declare const DEFAULT_TAG_REFRESH_MS = 1000;
+/**
+ * The bare-tag marker rows of the revalidation table (`pk = buildId`,
+ * `sk = tag`), which record when a tag was last revalidated and how.
+ *
+ * The table also holds the incremental cache's `tag#s3Key` mapping rows, which
+ * are its own business and stay in `S3CacheHandler`: only the markers mean the
+ * same thing to every handler. What an instance keeps of them between reads is
+ * {@link TrackedTagMarkers}.
+ */
+export declare class TagMarkerTable {
+    private readonly client;
+    private readonly tableName;
+    private readonly buildId;
+    constructor(client: DynamoDBClient, tableName: string, buildId: string);
+    /**
+     * Record `tag`'s revalidation at `now`. See {@link markerUpdate}.
+     *
+     * Returns the row as this write left it, so the instance that wrote it can
+     * track it rather than read it back: reads are eventually consistent, and a
+     * read-back racing replication could return the marker from before the write.
+     */
+    write(tag: string, now: number, durations: RevalidateDurations | undefined): Promise<TagMarker | undefined>;
+    /**
+     * The marker rows for `tags` that exist, by tag, in one `BatchGetItem` per
+     * {@link BATCH_GET_MAX_KEYS} tags rather than a `GetItem` each: a page
+     * carries its whole implicit `_N_T_/…` chain plus the app's own tags, a
+     * page with a few fetches checks each of them too, and every one is on the
+     * request path. A tag with no row is absent from the result.
+     */
+    read(tags: string[]): Promise<Map<string, TagMarker>>;
+}
+/**
+ * How long a revalidation log row is kept (`ttl`, epoch seconds). DynamoDB never
+ * deletes an item before its TTL, only some time after, so a reader that last
+ * queried less than this long ago (less a margin for writers' clocks) is sure
+ * to find every row it has not seen yet.
+ */
+export declare const REVALIDATION_LOG_TTL_MS: number;
+/** The most `Query` pages one {@link RevalidationLog.query} reads. */
+export declare const REVALIDATION_LOG_MAX_PAGES = 5;
+/** A revalidation read back from the log. */
+export interface RevalidationLogRow {
+    /** The row's sort key: unique per revalidation of a tag. */
+    sk: string;
+    /** When it was written, on the writer's `Date.now()`. */
+    at: number;
+    tag: string;
+    /** The marker fields the revalidation set, as {@link markerFor} returns them. */
+    marker: TagMarker;
+}
+/**
+ * The revalidation log: one row per tag revalidation (`pk = <buildId>#log`,
+ * `sk = <Date.now(), zero-padded>#<tag>`), which expires after
+ * {@link REVALIDATION_LOG_TTL_MS}.
+ *
+ * The marker rows stay the source of truth. The log exists so an instance
+ * can ask "what was revalidated since I last looked?" in one `Query`, instead
+ * of re-reading every tag it tracks to find out that almost none changed. Every
+ * marker row of a deployment shares one partition, and those re-reads from a
+ * handful of busy instances were enough to throttle it.
+ *
+ * The sort key's timestamp is the writer's wall clock (`Date.now()`), not the
+ * performance clock ({@link markerClock}) the marker values are stamped with by both
+ * handlers: it only orders rows for readers' cursors, which are on their own
+ * wall clocks, and is never compared with an entry's timestamp.
+ */
+export declare class RevalidationLog {
+    private readonly client;
+    private readonly tableName;
+    private readonly pk;
+    constructor(client: DynamoDBClient, tableName: string, buildId: string);
+    /**
+     * Record that `tag` was revalidated at `at` (`Date.now()`), setting `marker`.
+     *
+     * Two revalidations of `tag` in the same millisecond would share a sort key,
+     * and the second would overwrite the first. So the row is only written where
+     * its key is free, and on a collision it moves to the next millisecond, up
+     * to {@link LOG_PUT_ATTEMPTS} times.
+     */
+    put(tag: string, at: number, marker: TagMarker): Promise<void>;
+    /**
+     * The rows written at or after `since` (`Date.now()`), oldest first.
+     * `truncated` when there were more than {@link REVALIDATION_LOG_MAX_PAGES}
+     * pages of them, and `rows` is only the start.
+     *
+     * Eventually consistent: a row written a moment ago may not show yet, which
+     * is what the reader's lookback is for.
+     */
+    query(since: number): Promise<{
+        rows: RevalidationLogRow[];
+        truncated: boolean;
+    }>;
+}
+/**
+ * How far behind the last query's start the next one starts reading the log:
+ * the room for the `Query` being eventually consistent and for writers' clocks
+ * running behind the reader's. Rows inside it are read again, and dropped as
+ * already applied.
+ */
+export declare const REVALIDATION_LOG_LOOKBACK_MS = 5000;
+/**
+ * The longest {@link TrackedTagMarkers} trusts the log alone for a tag before
+ * reading its marker row again. The log is the fast path, but the marker rows
+ * are the source of truth: a log row whose write failed would otherwise be
+ * missed for as long as the tag stays tracked.
+ *
+ * Rolling, not all at once: each refresh re-reads at most
+ * {@link BATCH_GET_MAX_KEYS} of the tags due, oldest first. Re-reading them all
+ * together cost ~500 RCU at 1000 tags - a fleet started by one load test did it
+ * in the same minute, 12,800 RCU, and throttled - and would be ~5,000 RCU at
+ * {@link DEFAULT_MAX_TRACKED_TAGS}, past what the one partition serves in a
+ * second. Spread out, 10,000 tracked tags cost ~8 RCU a second per instance.
+ *
+ * Each tag is due at a random 75-100% of this after it was last read, so tags
+ * first read together - an instance warming up - do not all come due together
+ * again every interval: the load test that measured the rolling re-read saw
+ * its warm-up's reads return as a 30-36 RCU/s bump ten minutes later.
+ */
+export declare const DEFAULT_TAG_RESYNC_MS: number;
+/**
+ * How long since the last successful log query the log can still be trusted to
+ * hold every row not read yet: its TTL less a margin for writers' clocks. Past
+ * it - a Lambda frozen between invocations, a run of failed queries - the
+ * tracked markers are forgotten, to be read again as they are needed, and the
+ * log is followed from there.
+ */
+export declare const MAX_REVALIDATION_LOG_GAP_MS: number;
+/**
+ * The most tags one instance tracks. Past it the least recently used is
+ * forgotten, which costs a read the next time it is needed: an untracked tag
+ * is read before it is trusted.
+ *
+ * A tracked tag costs memory (~2 MB at this bound) and its share of the rolling
+ * re-read, not a read every refresh, so the bound is set by how many tags an
+ * instance really uses. Every path is a tag of its own (`_N_T_/<path>`), and at
+ * 1000 an app of 1000 tagged pages kept evicting what it was about to need:
+ * half its requests re-read a marker.
+ */
+export declare const DEFAULT_MAX_TRACKED_TAGS = 10000;
+/**
+ * The revalidation table's marker rows and its log, which are only ever used
+ * together, or neither for tags local to this process.
+ */
+export type TagTable = {
+    markers: TagMarkerTable;
+    log: RevalidationLog;
+} | {
+    markers?: undefined;
+    log?: undefined;
+};
+/** How {@link TrackedTagMarkers} is built. */
+export type TrackedTagMarkersOptions = TagTable & {
+    /**
+     * How often, at most, {@link TrackedTagMarkers.refresh} reads anything.
+     * @default DEFAULT_TAG_REFRESH_MS
+     */
+    refreshIntervalMs?: number;
+    maxTrackedTags?: number;
+    /** @see DEFAULT_TAG_RESYNC_MS */
+    resyncIntervalMs?: number;
+    /** The wall clock the log's cursor and the intervals are kept on. */
+    clock?: () => number;
+    /** `Math.random`, for when each tag's re-read comes due. */
+    random?: () => number;
+    debug?: (message: string) => void;
+};
+/**
+ * One instance's copy of the marker rows of the tags it has needed, kept
+ * current through the {@link RevalidationLog}: the process's one tag manifest
+ * (`sharedTagManifest`), for the `'use cache'` handlers and the incremental
+ * cache alike.
+ *
+ * Next.js's built-in `'use cache'` handler keeps tags in a module-level map
+ * (`tags-manifest.external.js`) that only its own `updateTags` writes, and its
+ * `refreshTags` is a no-op, so a `revalidateTag` on one instance never reaches
+ * the others: they keep serving the revalidated entry, including inside pages
+ * that are being re-rendered *because* of that revalidation. The
+ * `cacheHandlers` interface's answer is `refreshTags`, "called before starting
+ * a new request … to refresh the local tags manifest", and this is that
+ * manifest, backed by the same marker rows the incremental cache's
+ * `revalidateTag` writes (`pk = buildId`, `sk = tag`).
+ *
+ * The cost is bounded per instance, not per request:
+ * - {@link ensure} reads a tag's marker the first time it is needed and not
+ *   again until it is evicted, so a tag costs one read per instance, not one
+ *   per request.
+ * - {@link refresh}, at most once per `refreshIntervalMs`, sends one `Query`
+ *   for the log rows written since the last one, and applies those of tags
+ *   this instance tracks. Concurrent callers share it. Alongside, it re-reads
+ *   the markers of up to {@link BATCH_GET_MAX_KEYS} tags not read for
+ *   {@link DEFAULT_TAG_RESYNC_MS}, in one `BatchGetItem`.
+ * A revalidation on another instance is therefore seen within
+ * `refreshIntervalMs` (plus the query itself). The instance that ran it applies
+ * it itself, at once, with {@link set}.
+ */
+export declare class TrackedTagMarkers {
+    private readonly markers;
+    private readonly log;
+    private readonly refreshIntervalMs;
+    private readonly maxTrackedTags;
+    private readonly resyncIntervalMs;
+    private readonly clock;
+    private readonly random;
+    private readonly debug;
+    /** By tag, least recently used first. */
+    private readonly tags;
+    /**
+     * When each tracked tag's marker is due to be read again: a random 75-100%
+     * of `resyncIntervalMs` after it was last known from the table - read,
+     * written here, or new. In the order they became known, least recent first.
+     */
+    private readonly dueAt;
+    private readonly reading;
+    /**
+     * Log rows for tags whose first read is in flight, merged by tag: the read
+     * may have been answered before the revalidation, so they are applied to its
+     * result rather than dropped.
+     */
+    private readonly pendingRows;
+    /** Tracked tags whose read failed, for the next refresh to read again. */
+    private readonly unread;
+    private lastRefresh;
+    private refreshing;
+    /**
+     * Where the next log query starts (`clock()`): the last successful one's
+     * start, less {@link REVALIDATION_LOG_LOOKBACK_MS}.
+     */
+    private cursor;
+    /** When the last successful log query started, or the log was first read. */
+    private lastLogRead;
+    /** Log rows at or after the cursor already applied, by sort key. */
+    private readonly applied;
+    /** {@link update}s of the current turn, by their arguments. */
+    private readonly updating;
+    constructor(options: TrackedTagMarkersOptions);
+    /** `tag`'s marker as this instance knows it, if it tracks `tag`. */
+    get(tag: string): TagMarker | undefined;
+    /**
+     * Track `tag` with `marker`: what this instance just wrote, which it knows
+     * without reading it back.
+     */
+    set(tag: string, marker: TagMarker): void;
+    /**
+     * Note a use of `tags`: those of an entry this instance just stored.
+     *
+     * With the table, a tag not tracked yet is left untracked, to be read by
+     * {@link ensure} the first time an entry needs it. Nothing revalidated before
+     * the new entry was created applies to *it*, but tracking is per tag, not per
+     * entry: tracking the tag with an empty marker would also vouch for every
+     * older entry that carries it - one another instance stored in S3, or one
+     * this instance kept in memory across a {@link forget} - and a revalidation
+     * from before the log's cursor would go unseen until the rolling re-read.
+     *
+     * Without the table every revalidation is this process's own, applied with
+     * {@link set}, so a tag is tracked at once.
+     */
+    track(tags: readonly string[]): void;
+    /**
+     * Track `tags` as they are known now, without reading them, with an empty
+     * marker for any not tracked yet.
+     */
+    private trackUnread;
+    /**
+     * Read the markers of whichever of `tags` this instance does not track yet.
+     * Needed before judging an entry this instance did not create, since its
+     * tags may have been revalidated at any time before.
+     */
+    ensure(tags: readonly string[]): Promise<void>;
+    /**
+     * Catch up on revalidations other instances ran, at most once per
+     * `refreshIntervalMs`. See {@link TrackedTagMarkers} for the cost.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Record a revalidation of `tags`: here at once, and in the revalidation
+     * table for every other instance - the marker row plus a log row per tag.
+     *
+     * Next.js calls `revalidateTag` on the incremental cache and `updateTags` on
+     * every distinct `cacheHandlers` entry, all in one synchronous loop
+     * (`revalidation-utils`), and all of them share this manifest. So an
+     * identical call in the same turn joins the first instead of writing the
+     * rows again. One in a later turn is a revalidation of its own, even while
+     * the first one's writes are in flight, and gets its own, later, marker.
+     * Never rejects: resolves `false` when a row failed to write (the error is
+     * logged), so other instances may not see it.
+     */
+    update(tags: readonly string[], durations: RevalidateDurations | undefined): Promise<boolean>;
+    /**
+     * What the tracked markers say about an entry carrying `tags`, created at
+     * `createdAt`: the most severe answer of any of them.
+     */
+    state(tags: readonly string[], createdAt: number): RevalidationState;
+    /**
+     * `getExpiration`'s answer: the latest time any of `tags` expired, `0` if
+     * none has. Only expirations already past count - a profile's future
+     * `expire` is not an expiration yet - and a stale mark does not, matching
+     * Next.js's default handler, which reads only `expired` for implicit tags.
+     */
+    expiration(tags: readonly string[]): number;
+    private write;
+    /**
+     * Put `tag`'s log row, stamped on the wall clock (the marker values are on
+     * Next.js's: see {@link RevalidationLog}).
+     *
+     * Readers only look {@link REVALIDATION_LOG_LOOKBACK_MS} behind their last
+     * query, so a row that shows up much later than its timestamp - a slow
+     * connection, retries under throttling - is behind every cursor and never
+     * read. A slow put is therefore made again under a fresh timestamp, which
+     * readers will see; one slow twice is reported as a failure.
+     */
+    private putLogRow;
+    /**
+     * One refresh started at `at`: the log rows since the cursor, and the next
+     * slice of the rolling re-read.
+     *
+     * A failed query changes nothing but the log: the tags stay tracked as they
+     * were, and the next refresh asks again from the same cursor.
+     */
+    private sync;
+    /**
+     * The tags to read on this refresh, at most one `BatchGetItem`'s worth:
+     * those whose read failed, then those whose re-read has come due, in the
+     * order they were last read.
+     */
+    private due;
+    /**
+     * Forget every tracked marker, and follow the log from `at`: what is needed
+     * next is read from its marker as it is needed, spread over the requests
+     * that need it, rather than every tracked tag re-read at once.
+     */
+    private forget;
+    /**
+     * Move the cursor forward to `cursor`, forgetting applied rows before it:
+     * no query returns them again.
+     */
+    private advance;
+    /**
+     * Read `tags` from the table, and report whether that worked. A read that
+     * fails leaves them tracked as they were, and the next refresh reads them
+     * again: the same "assume the entry is valid" the incremental cache has
+     * always answered with, rather than a read on every request while DynamoDB
+     * is unavailable.
+     */
+    private readInto;
+    private takePendingRows;
+    /** Record that `tag`'s marker was known from the table at `at`. */
+    private known;
+    private remember;
+    private touch;
+}
+/**
+ * A marker as read from the table or the log, keeping whatever this instance
+ * already knows that the read does not show yet: reads are eventually
+ * consistent, and a read straight after this instance's own revalidation could
+ * otherwise take it back.
+ */
+export declare function mergeMarkers(local: TagMarker | undefined, remote: TagMarker | undefined): TagMarker;
+/**
+ * The cache bucket, as the handlers use it: whole objects read and written as
+ * UTF-8 text under the keys above.
+ */
+export declare class CacheBucket {
+    private readonly client;
+    private readonly bucketName;
+    constructor(client: S3Client, bucketName: string);
+    /**
+     * The body of the object at `key`, or `undefined` when there is none (`NoSuchKey`, or an
+     * empty response body). Any other error is thrown: the handlers disagree on
+     * whether one is worth logging.
+     */
+    get(key: string): Promise<string | undefined>;
+    /** Write `body` as a JSON object at `key`. */
+    putJson(key: string, body: string): Promise<void>;
+}