nuxt-compressed-cache 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manthankumar Satani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# nuxt-compressed-cache
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Serve Nuxt pages from pre-compressed cached copies.
+
+Nitro's `swr` cache stores each response as a JSON entry and sends it uncompressed, so every hit parses the
+entry, and the page is compressed again on every hit by whatever sits in front (a proxy or CDN), or goes out
+uncompressed. This module stores rendered pages already compressed with brotli and gzip, then sends the stored
+bytes as they are. A hit reads a small metadata entry and the compressed bytes. Compression runs once per
+render instead of once per request.
+
+- Stale-while-revalidate, configured per route like Nitro's `swr`
+- Concurrent misses render once (per server process)
+- Content negotiation by `Accept-Encoding` weights, including clients that accept no compression
+- `ETag` and `304 Not Modified`
+- Caches the `_payload.json` Nuxt fetches on client-side navigation, per build, via `isr: true` ([Payloads](#payloads))
+- Pages from an older build are rendered again after a deploy
+- Helpers to expire, remove and prune entries
+
+> Requires Nuxt 5 (Nitro 3), deployed as a Node server (VPS, Docker, Coolify…). See [Deployment](#deployment).
+
+## Why
+
+When your own server renders and serves every request, each cache hit still costs work. Nitro's `swr` reads a
+JSON entry, parses it and sends the page uncompressed. Then either your proxy compresses the same page again on
+every hit, a CDN does it at the edge, or it goes out uncompressed. This module moves that work to render time:
+
+- **Less work per hit.** A hit reads the stored bytes and sends them as they are. The page itself is never
+  parsed or compressed on a hit.
+- **Smaller responses from your server.** Pages leave your server compressed, even when nothing in front of it
+  compresses. Compression is paid once per render, so a higher brotli quality costs nothing per hit.
+- **Smaller storage.** Entries are stored compressed.
+- **Client-side navigation is cached too.** Nuxt's `_payload.json` is cached per build, without also turning on
+  Nitro's cache.
+- **Safe across deploys.** After a deploy, pages stored by the previous build render again before they are
+  sent.
+
+### You might not need this
+
+This is a niche module. Use Nitro's `swr` or `isr` instead, or nothing at all, if:
+
+- you deploy to Vercel, Netlify, Cloudflare or another serverless or edge platform. They provide their own
+  caching and compression, and the module isn't built for them;
+- a CDN in front of your server already caches your HTML;
+- your pages can be prerendered, so there's nothing to render at request time;
+- your traffic is low or your pages are cheap to render, so `swr` is fast enough;
+- your pages differ per visitor by something other than a cookie (such as language or user agent), since every
+  visitor gets the same copy.
+
+## Install
+
+```bash
+pnpm add nuxt-compressed-cache
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-compressed-cache'],
+  routeRules: {
+    '/': { compressedCache: { maxAge: 60 * 60 } },
+    '/blog/**': { compressedCache: { maxAge: 60 * 60 * 24 } },
+  },
+})
+```
+
+Responses served by the cache carry an `x-cache` header: `HIT`, `STALE` or `MISS`. Responses it passes
+through without storing (an error, a cookie, a bypassed request) don't.
+
+The cache does nothing in development or while prerendering.
+
+## Storage
+
+By default, entries go to Nitro's `cache` storage mount. If that mount isn't backed by persistent storage in
+production, entries are lost on every restart. To use a dedicated persistent mount:
+
+```ts
+export default defineNuxtConfig({
+  compressedCache: {
+    // an unstorage driver, mounted as `compressed-cache`
+    storage: { driver: 'fs', base: './.data/compressed-cache' },
+  },
+})
+```
+
+You can also pass the name of a mount you configured yourself, for example `storage: 'redis'`.
+
+## Route rule
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/products/**': {
+      compressedCache: {
+        maxAge: 3600,
+        staleMaxAge: 86400,
+        allowQuery: ['page'],
+        bypassCookies: ['session'],
+      },
+    },
+  },
+})
+```
+
+| Option | Description |
+| --- | --- |
+| `maxAge` | Seconds a copy is fresh. |
+| `staleMaxAge` | Seconds a copy may still be served after `maxAge` while it re-renders in the background. Unset serves stale copies until they are replaced. `0` always waits for a fresh render. When set, entries also get a storage TTL of `maxAge + staleMaxAge`, on drivers that support one. |
+| `allowQuery` | Query params that get their own entry. Other params are ignored for lookups, and a request carrying them is never stored. |
+| `bypassCookies` | Requests carrying any of these cookies skip the cache, for example a session cookie. |
+
+## Module options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `storage` | `'cache'` | Name of a Nitro storage mount, or unstorage driver options mounted as `compressed-cache`. |
+| `prefix` | `'compressed-cache'` | Key prefix inside the storage mount. |
+| `encodings` | `['br', 'gzip']` | Copies to store. Storing only `br` drops the gzip copy, and clients that don't accept brotli are then converted on the fly. Clients that accept no compression always get a copy decompressed on the fly. |
+| `brotliQuality` | `6` | Brotli quality, used once per render. |
+| `gzipLevel` | `6` | Gzip level, used once per render. |
+| `statusHeader` | `'x-cache'` | Header that reports `HIT`, `STALE` or `MISS`. `false` omits it. |
+| `invalidateOnBuild` | `true` | Tie entries to the build. After a deploy that keeps the storage, pages render again before they are sent, and payloads are kept per build (see [Payloads](#payloads)). |
+| `cleanup` | `false` | Enable Nitro's scheduled pruning task. `true` runs daily at 04:00 and removes expired entries (see [Server helpers](#server-helpers)). An object can override `schedule` (cron) and set `olderThan` (seconds) to remove by age instead. |
+
+## Server helpers
+
+These are auto-imported in server code. A `path` also covers that page's `_payload.json`.
+
+```ts
+// mark entries stale: each is served stale while it re-renders (re-rendered first when `staleMaxAge` is 0)
+await expireCompressedCache({ path: '/blog/my-post' })
+await expireCompressedCache({ pathPrefix: '/blog/' })
+
+// delete entries: the next request renders fresh
+await removeCompressedCache({ path: '/blog/my-post' })
+
+// delete expired entries: past `maxAge` (plus `staleMaxAge` when set) of their page's current route rule,
+// and entries whose page no longer has a `compressedCache` rule
+await pruneCompressedCache()
+
+// or delete entries rendered more than `olderThan` seconds ago, whatever their rule
+await pruneCompressedCache({ olderThan: 7 * 24 * 60 * 60 })
+```
+
+Without `staleMaxAge`, a stale copy is served until a visit replaces it, so pruning only removes pages nobody
+has visited since they expired. Their next visitor waits for a render instead of getting the stale copy.
+
+Storage drivers without a TTL (such as `fs`) never drop entries on their own. Enable the built-in cleanup
+task with `compressedCache: { cleanup: true }`, which runs `pruneCompressedCache()` daily at 04:00, or
+customize it:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  compressedCache: {
+    cleanup: {
+      schedule: '0 */6 * * *',
+      // remove by age instead of expiry
+      olderThan: 7 * 24 * 60 * 60,
+    },
+  },
+})
+```
+
+Cleanup is disabled by default. When enabled, the module enables Nitro tasks, registers
+`compressed-cache:prune` and adds its schedule alongside existing tasks. It uses the configured storage and
+prefix, removing each pruned entry's metadata and compressed copies. Schedules use the server's timezone.
+
+The built-in task only prunes. For more control, such as clearing the cache when the disk is almost full,
+leave `cleanup` off and call `pruneCompressedCache` from your own task:
+
+```ts
+// server/tasks/compressed-cache/prune.ts
+import { defineTask } from 'nitro/task'
+
+export default defineTask({
+  meta: { name: 'compressed-cache:prune' },
+  async run() {
+    return { result: await pruneCompressedCache() }
+  },
+})
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    experimental: { tasks: true },
+    scheduledTasks: { '0 4 * * *': 'compressed-cache:prune' },
+  },
+})
+```
+
+## What gets cached
+
+A response is stored only when all of these are true:
+
+- it is a `GET` with status `200`;
+- it is HTML or JSON;
+- it has no `Set-Cookie` header;
+- its `Cache-Control` is not `no-store` or `private`;
+- it isn't already encoded (`Content-Encoding`).
+
+When a background re-render can't be stored (a `404`, a redirect, `private`, `no-store`, a cookie), the stored
+copy is removed. A server error (`5xx`) keeps it, so a short outage doesn't empty the cache.
+
+> [!WARNING]
+> There are no per-header variants. Every visitor gets the same stored copy, whatever their `Accept-Language`, 
+> user agent or cookies. Don't cache pages that render differently per visitor, or list the cookie that changes 
+> them in `bypassCookies`.
+
+## Payloads
+
+A direct visit gets the cached HTML, with the page's data inlined. On client-side navigation, Nuxt fetches
+`<page>/_payload.json?_b=<build id>` instead, which is cached the same way.
+
+At runtime, Nuxt only serves `_payload.json` on routes it sees as cached, through an `isr` or `cache` rule.
+`cache` would also turn on Nitro's own cache, so on Node server presets the module adds `isr: true` to every
+`compressedCache` route instead, which those presets ignore. A route that sets `isr` itself keeps its value.
+
+Payloads are kept per build, like the `_b` param Nuxt adds to them:
+
+| Request | Served from | Stored |
+| --- | --- | --- |
+| `_b` is the running build, or no `_b` | The running build's entry | Yes |
+| `_b` is an older build | That build's entry while it is fresh, so an open tab keeps the data its code expects | Never |
+| Any other `_b` | Rendered without the cache | Never |
+
+## Deployment
+
+The module is built for long-running Node servers: a VPS, Docker or a platform like Coolify, with a `node-*`,
+`bun` or `deno-server` preset. It relies on:
+
+- `node:zlib` and `node:crypto`;
+- a long-running process, which merges concurrent renders in memory (per process) and re-renders in the
+  background after responding;
+- persistent storage for the entries.
+
+On other presets (serverless and edge platforms such as Vercel, Netlify and Cloudflare), the module doesn't add
+`isr`, because there it can mean something else (on Vercel it turns on Vercel's own cache). It logs a warning
+instead, and pages there get no `_payload.json` for client-side navigation unless you set `isr` or `cache`
+yourself.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev:prepare
+pnpm dev        # playground
+pnpm test       # unit and e2e tests
+pnpm test:types
+pnpm lint
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/module.d.mts

@@ -0,0 +1,27 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { CompressedCacheConfig } from '../dist/runtime/compressed-cache.js';
+
+interface CompressedCacheModuleOptions extends Omit<CompressedCacheConfig, 'storage' | 'version'> {
+    /** Name of an existing Nitro storage mount, or unstorage driver options mounted as `compressed-cache`. */
+    storage?: string | {
+        driver: string;
+        [option: string]: unknown;
+    };
+    /** Treat entries from a previous build as stale, so they re-render after a deploy that keeps the storage. */
+    invalidateOnBuild?: boolean;
+    /** Enable scheduled pruning, daily at 04:00 by default, of entries past their route rule's `maxAge` and `staleMaxAge`. */
+    cleanup?: boolean | {
+        /** Cron expression for Nitro's task runner. */
+        schedule?: string;
+        /** Remove entries rendered more than this many seconds ago, instead of when they expire. */
+        olderThan?: number;
+    };
+}
+/**
+ * Serves `compressedCache` route rules from pre-compressed copies, configured like Nitro's `swr`:
+ * `routeRules: { '/blog/**': { compressedCache: { maxAge: 3600 } } }`.
+ */
+declare const _default: _nuxt_schema.NuxtModule<CompressedCacheModuleOptions, CompressedCacheModuleOptions, false>;
+
+export { _default as default };
+export type { CompressedCacheModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-compressed-cache",
+  "configKey": "compressedCache",
+  "compatibility": {
+    "nuxt": ">=5.0.0-0"
+  },
+  "version": "0.1.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,80 @@
+import { defineNuxtModule, createResolver, useLogger, addServerHandler, addServerImports, addTypeTemplate } from 'nuxt/kit';
+
+const SERVER_PRESET = /^(?:node-|bun$|deno-server$|nitro-)/;
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-compressed-cache",
+    configKey: "compressedCache",
+    compatibility: { nuxt: ">=5.0.0-0" }
+  },
+  defaults: {
+    storage: "cache",
+    prefix: "compressed-cache",
+    encodings: ["br", "gzip"],
+    brotliQuality: 6,
+    gzipLevel: 6,
+    statusHeader: "x-cache",
+    invalidateOnBuild: true,
+    cleanup: false
+  },
+  setup({ storage, invalidateOnBuild, cleanup, ...options }, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const { schedule = "0 4 * * *", olderThan } = typeof cleanup === "object" ? cleanup : {};
+    const mount = typeof storage === "object" ? "compressed-cache" : storage ?? "cache";
+    if (typeof storage === "object") {
+      nuxt.options.nitro.storage = { ...nuxt.options.nitro.storage, [mount]: storage };
+    }
+    nuxt.options.runtimeConfig.compressedCache = {
+      ...options,
+      storage: mount,
+      version: invalidateOnBuild ? nuxt.options.buildId : void 0,
+      cleanup: cleanup ? { olderThan } : false
+    };
+    if (cleanup) {
+      const nitro = nuxt.options.nitro;
+      nitro.experimental ||= {};
+      nitro.experimental.tasks = true;
+      nitro.tasks ||= {};
+      nitro.tasks["compressed-cache:prune"] = { handler: resolver.resolve("./runtime/tasks/prune") };
+      nitro.scheduledTasks ||= {};
+      const scheduled = nitro.scheduledTasks[schedule];
+      nitro.scheduledTasks[schedule] = [.../* @__PURE__ */ new Set([...Array.isArray(scheduled) ? scheduled : scheduled ? [scheduled] : [], "compressed-cache:prune"])];
+    }
+    nuxt.hook("nitro:init", async (nitro) => {
+      const cached = Object.entries(nitro.options.routeRules).filter(([, rules]) => rules.compressedCache && rules.isr === void 0);
+      if (!cached.length) {
+        return;
+      }
+      if (!SERVER_PRESET.test(nitro.options.preset)) {
+        useLogger("nuxt-compressed-cache").warn(`Built for Node servers, the \`${nitro.options.preset}\` preset gets no \`_payload.json\` for client navigation.`);
+        return;
+      }
+      await nitro.updateConfig({
+        routeRules: { ...nitro.options.routeRules, ...Object.fromEntries(cached.map(([route, rules]) => [route, { ...rules, isr: true }])) }
+      });
+      nitro.routing.sync();
+    });
+    addServerHandler({ middleware: true, handler: resolver.resolve("./runtime/middleware") });
+    addServerImports(
+      ["expireCompressedCache", "removeCompressedCache", "pruneCompressedCache"].map((name) => ({ name, from: resolver.resolve("./runtime/server-utils") }))
+    );
+    addTypeTemplate({
+      filename: "types/compressed-cache.d.ts",
+      getContents: () => `import type { CompressedCacheRule } from ${JSON.stringify(resolver.resolve("./runtime/compressed-cache"))}
+
+declare module 'nitro/types' {
+  interface RouteRules {
+    compressedCache?: CompressedCacheRule
+  }
+  interface RouteRuleConfig {
+    /** Serve this route from pre-compressed copies, re-rendered in the background after \`maxAge\` seconds. */
+    compressedCache?: CompressedCacheRule
+  }
+}
+export {}
+`
+    }, { nitro: true, nuxt: true, node: true, shared: true });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/compressed-cache.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Compressed cache that stores rendered HTML and payloads pre-compressed (brotli and/or gzip) and serves the bytes as-is,
+ * so a hit costs a small read instead of a JSON parse, and a render pays compression once instead of per request.
+ * It follows Nitro's route cache rules (stale-while-revalidate, 200 only, no cookies) without header or cookie variants.
+ */
+export type Encoding = 'br' | 'gzip';
+/** Per route settings, set through the `compressedCache` route rule. */
+export interface CompressedCacheRule {
+    /** Seconds a copy is fresh. */
+    maxAge: number;
+    /**
+     * Seconds a copy may still be served while it re-renders in the background, after `maxAge`.
+     * Unset serves stale copies until replaced, `0` always waits for a fresh render.
+     * When set, entries also get a storage TTL of `maxAge + staleMaxAge`.
+     */
+    staleMaxAge?: number;
+    /** Query params that get their own entry, any other param is ignored for lookups and never stored. */
+    allowQuery?: string[];
+    /** Requests carrying any of these cookies skip the cache, for example a session cookie. */
+    bypassCookies?: string[];
+}
+export interface CompressedCacheOptions extends CompressedCacheConfig {
+    /** The rule for a page pathname, or `undefined` to leave the request alone. A payload is looked up by its page. */
+    rule: ({ pathname }: {
+        pathname: string;
+    }) => CompressedCacheRule | undefined;
+}
+/** Settings shared by every cached route, the module passes these through runtime config. */
+export interface CompressedCacheConfig {
+    /** Storage mount for entries. */
+    storage?: string;
+    /** Key prefix inside the storage mount. */
+    prefix?: string;
+    /**
+     * Compressed copies to store. Both serve every client as-is, brotli only halves storage
+     * and converts the rare gzip-only request on the fly.
+     */
+    encodings?: Encoding[];
+    /** Brotli quality used once per render. */
+    brotliQuality?: number;
+    /** Gzip level used once per render. */
+    gzipLevel?: number;
+    /** Response header that reports `HIT`, `STALE` or `MISS`, `false` to omit it. */
+    statusHeader?: string | false;
+    /**
+     * The build id. A page entry stored by another build is rendered again before it is sent,
+     * and payloads are kept per build like the `_b` param Nuxt adds to them.
+     */
+    version?: string;
+}
+/** Where entries live, also what the invalidation helpers need. */
+export interface CompressedCacheLocation {
+    storage?: string;
+    prefix?: string;
+}
+export declare const DEFAULT_STORAGE = "cache";
+export declare const DEFAULT_PREFIX = "compressed-cache";
+/**
+ * Picks the available encoding the client weights highest (`q`, default 1, `*` for unlisted ones),
+ * brotli on a tie, and never one the client did not accept.
+ *
+ * @returns The encoding to send, or `undefined` when the client accepts none of them.
+ */
+export declare function negotiateEncoding(acceptEncoding: string | null, available?: Encoding[]): Encoding | undefined;
+/**
+ * Marks cached copies stale, each is served once more while it re-renders in the background.
+ * Pass `path` for one page (all its allowed query variants and its payload) or `pathPrefix` for every page under it.
+ *
+ * @returns How many entries were expired.
+ */
+export declare function expireCompressedCache(target: CompressedCacheLocation & {
+    path: string;
+} | CompressedCacheLocation & {
+    pathPrefix: string;
+}): Promise<number>;
+/**
+ * Deletes cached copies, the next request renders fresh.
+ * Pass `path` for one page (all its allowed query variants and its payload) or `pathPrefix` for every page under it.
+ *
+ * @returns How many entries were removed.
+ */
+export declare function removeCompressedCache(target: CompressedCacheLocation & {
+    path: string;
+} | CompressedCacheLocation & {
+    pathPrefix: string;
+}): Promise<number>;
+/**
+ * Deletes entries past the `maxAge` (plus `staleMaxAge` when set) of their page's current route rule,
+ * and entries whose page no longer has a rule, or, with `olderThan`, entries rendered more than that many
+ * seconds ago. Judged by each entry's own render time, so it works on every storage driver,
+ * including ones without file times (memory, redis, KV). Meant for a scheduled Nitro task.
+ *
+ * @returns How many entries were removed.
+ */
+export declare function pruneCompressedCache({ storage, prefix, ...by }: CompressedCacheLocation & ({
+    olderThan: number;
+} | {
+    rule: CompressedCacheOptions['rule'];
+})): Promise<number>;
+/** Creates the compressed cache middleware. */
+export declare function defineCompressedCache(options: CompressedCacheOptions): import("h3").Middleware;

package/dist/runtime/compressed-cache.js

@@ -0,0 +1,288 @@
+import { createHash, randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+import { brotliCompress, brotliCompressSync, brotliDecompressSync, constants, gunzipSync, gzip, gzipSync } from "node:zlib";
+import { serverFetch } from "nitro/app";
+import { defineMiddleware, toResponse } from "nitro/h3";
+import { useStorage } from "nitro/storage";
+const brotliAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+export const DEFAULT_STORAGE = "cache";
+export const DEFAULT_PREFIX = "compressed-cache";
+const ENCODINGS = ["br", "gzip"];
+const ENCODING_FILE = { br: "br", gzip: "gz" };
+const SKIPPED_HEADERS = /* @__PURE__ */ new Set(["content-encoding", "content-length", "transfer-encoding", "set-cookie", "etag", "vary"]);
+const CACHEABLE_TYPE = /^(?:text\/html|application\/json)\b/i;
+const REVALIDATE_HEADER = "x-compressed-cache-revalidate";
+const PAYLOAD_SUFFIX = "/_payload.json";
+const BUILD_PARAM = "_b";
+const REVALIDATE_TOKEN = randomUUID();
+const inflight = /* @__PURE__ */ new Map();
+export function negotiateEncoding(acceptEncoding, available = ENCODINGS) {
+  const weights = /* @__PURE__ */ new Map();
+  for (const part of (acceptEncoding ?? "").toLowerCase().split(",")) {
+    const [name, ...params] = part.split(";").map((value) => value.trim());
+    const quality = params.find((param) => param.startsWith("q="));
+    if (name) {
+      weights.set(name, quality ? Number(quality.slice(2)) || 0 : 1);
+    }
+  }
+  let best;
+  let bestWeight = 0;
+  for (const encoding of ENCODINGS) {
+    const weight = weights.get(encoding) ?? weights.get("*") ?? 0;
+    if (available.includes(encoding) && weight > bestWeight) {
+      best = encoding;
+      bestWeight = weight;
+    }
+  }
+  return best;
+}
+function isCacheable(response) {
+  const cacheControl = response.headers.get("cache-control") ?? "";
+  const encoding = response.headers.get("content-encoding");
+  return response.status === 200 && !response.headers.has("set-cookie") && !/\b(?:no-store|private)\b/i.test(cacheControl) && (!encoding || encoding === "identity") && CACHEABLE_TYPE.test(response.headers.get("content-type") ?? "");
+}
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 32);
+}
+function pathKey({ prefix, pathname }) {
+  return `${prefix}:${hash(pathname)}`;
+}
+function entryKey({ prefix, pathname, query }) {
+  return `${pathKey({ prefix, pathname })}:${query ? hash(query) : "default"}`;
+}
+function normalizeQuery({ search, allowQuery = [], payload, version }) {
+  const params = [...new URLSearchParams(search)];
+  const keyed = payload ? params.filter(([name]) => name !== BUILD_PARAM) : params;
+  const allowed = keyed.filter(([name]) => allowQuery.includes(name)).sort(([a], [b]) => a.localeCompare(b));
+  const extra = allowed.length !== keyed.length;
+  if (!payload || !version) {
+    return { query: new URLSearchParams(allowed).toString(), extra, currentBuild: true };
+  }
+  const build = new URLSearchParams(search).get(BUILD_PARAM) ?? version;
+  return { query: new URLSearchParams([...allowed, [BUILD_PARAM, build]]).toString(), extra, currentBuild: build === version };
+}
+function pagePathname(path) {
+  const pathname = path.split("?")[0];
+  return pathname.endsWith(PAYLOAD_SUFFIX) ? pathname.slice(0, -PAYLOAD_SUFFIX.length) || "/" : pathname;
+}
+function payloadPath(path) {
+  return path.replace(/\/$/, "") + PAYLOAD_SUFFIX;
+}
+function hasCookie({ cookieHeader, names }) {
+  const present = (cookieHeader ?? "").split(";").map((cookie) => cookie.split("=")[0].trim());
+  return names.some((name) => present.includes(name));
+}
+function matchesEtag({ ifNoneMatch, etag }) {
+  const opaque = etag.replace(/^W\//, "");
+  return (ifNoneMatch ?? "").split(",").some((tag) => {
+    const value = tag.trim();
+    return value === "*" || value.replace(/^W\//, "") === opaque;
+  });
+}
+async function removeEntry({ storage, entry }) {
+  const store = useStorage(storage);
+  await Promise.all(["meta", ...Object.values(ENCODING_FILE)].map((file) => store.removeItem(`${entry}:${file}`)));
+}
+async function compressStored({ encoding, raw, config }) {
+  return encoding === "br" ? brotliAsync(raw, { params: { [constants.BROTLI_PARAM_QUALITY]: config.brotliQuality ?? 6, [constants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength } }) : gzipAsync(raw, { level: config.gzipLevel ?? 6 });
+}
+function convert({ body, from, to }) {
+  const raw = from === "br" ? brotliDecompressSync(body) : gunzipSync(body);
+  if (to === "br") {
+    return brotliCompressSync(raw, { params: { [constants.BROTLI_PARAM_QUALITY]: 1 } });
+  }
+  return to === "gzip" ? gzipSync(raw, { level: 1 }) : raw;
+}
+async function readPage({ storage, key, encoding }) {
+  const store = useStorage(storage);
+  const meta = await store.getItem(`${key}:meta`);
+  if (!meta) {
+    return;
+  }
+  const bytes = await store.getItemRaw(`${key}:${ENCODING_FILE[encoding]}`);
+  if (!bytes || bytes.byteLength !== meta.size[encoding]) {
+    return;
+  }
+  return { meta, body: { [encoding]: bytes } };
+}
+async function renderPage({ event, next, storage, key, path, rule, encodings, config }) {
+  const response = await toResponse(await next(), event);
+  if (!isCacheable(response)) {
+    return { response };
+  }
+  const raw = new Uint8Array(await response.arrayBuffer());
+  const compressed = await Promise.all(encodings.map((encoding) => compressStored({ encoding, raw, config })));
+  const body = {};
+  const size = {};
+  encodings.forEach((encoding, index) => {
+    body[encoding] = compressed[index];
+    size[encoding] = compressed[index].byteLength;
+  });
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    if (!SKIPPED_HEADERS.has(name)) {
+      headers[name] = value;
+    }
+  });
+  const meta = {
+    path,
+    status: response.status,
+    headers,
+    etag: `W/"${createHash("sha1").update(raw).digest("base64url")}"`,
+    createdAt: Date.now(),
+    version: config.version,
+    size
+  };
+  const store = useStorage(storage);
+  const ttl = rule.staleMaxAge === void 0 ? void 0 : { ttl: rule.maxAge + rule.staleMaxAge };
+  try {
+    await Promise.all(encodings.map((encoding) => store.setItemRaw(`${key}:${ENCODING_FILE[encoding]}`, body[encoding], ttl)));
+    await store.setItem(`${key}:meta`, meta, ttl);
+  } catch (error) {
+    console.error("[compressed-cache] storing failed", error);
+  }
+  return { page: { meta, body } };
+}
+function sendPage({ event, page, source, target, state, statusHeader }) {
+  const headers = new Headers(page.meta.headers);
+  headers.set("etag", page.meta.etag);
+  headers.append("vary", "accept-encoding");
+  if (statusHeader) {
+    headers.set(statusHeader, state);
+  }
+  if (matchesEtag({ ifNoneMatch: event.req.headers.get("if-none-match"), etag: page.meta.etag })) {
+    return new Response(null, { status: 304, headers });
+  }
+  const stored = page.body[source];
+  const body = source === target ? stored : convert({ body: stored, from: source, to: target });
+  if (target) {
+    headers.set("content-encoding", target);
+  }
+  headers.set("content-length", String(body.byteLength));
+  return new Response(event.req.method === "HEAD" ? null : body, { status: page.meta.status, headers });
+}
+function revalidate({ event, key, path }) {
+  if (inflight.has(key)) {
+    return;
+  }
+  const task = serverFetch(new URL(path, event.url.origin), { headers: { [REVALIDATE_HEADER]: REVALIDATE_TOKEN } }).then(async (response) => {
+    await response.body?.cancel();
+    return void 0;
+  }).catch((error) => {
+    console.error("[compressed-cache] revalidation failed", error);
+    return void 0;
+  }).finally(() => inflight.delete(key));
+  inflight.set(key, task);
+  event.req.waitUntil?.(task);
+}
+async function findEntries({ storage = DEFAULT_STORAGE, prefix = DEFAULT_PREFIX, path, pathPrefix }) {
+  const store = useStorage(storage);
+  const bases = path ? [path, payloadPath(path)].map((pathname) => pathKey({ prefix, pathname })) : [prefix];
+  const metaKeys = (await Promise.all(bases.map((base) => store.getKeys(base)))).flat().filter((key) => key.endsWith(":meta"));
+  const entries = [];
+  for (const metaKey of metaKeys) {
+    if (!path) {
+      const meta = await store.getItem(metaKey);
+      if (!meta?.path.startsWith(pathPrefix ?? "/")) {
+        continue;
+      }
+    }
+    entries.push(metaKey.slice(0, -":meta".length));
+  }
+  return entries;
+}
+export async function expireCompressedCache(target) {
+  const store = useStorage(target.storage ?? DEFAULT_STORAGE);
+  const entries = await findEntries(target);
+  for (const entry of entries) {
+    const meta = await store.getItem(`${entry}:meta`);
+    if (meta) {
+      await store.setItem(`${entry}:meta`, { ...meta, expired: true });
+    }
+  }
+  return entries.length;
+}
+export async function removeCompressedCache(target) {
+  const entries = await findEntries(target);
+  await Promise.all(entries.map((entry) => removeEntry({ storage: target.storage ?? DEFAULT_STORAGE, entry })));
+  return entries.length;
+}
+export async function pruneCompressedCache({ storage = DEFAULT_STORAGE, prefix = DEFAULT_PREFIX, ...by }) {
+  const store = useStorage(storage);
+  const now = Date.now();
+  const metaKeys = (await store.getKeys(prefix)).filter((key) => key.endsWith(":meta"));
+  let removed = 0;
+  for (const metaKey of metaKeys) {
+    const meta = await store.getItem(metaKey);
+    const rule = meta && "rule" in by ? by.rule({ pathname: pagePathname(meta.path) }) : void 0;
+    const lifetime = "olderThan" in by ? by.olderThan : rule ? rule.maxAge + (rule.staleMaxAge ?? 0) : 0;
+    if (meta && meta.createdAt + lifetime * 1e3 > now) {
+      continue;
+    }
+    await removeEntry({ storage, entry: metaKey.slice(0, -":meta".length) });
+    removed++;
+  }
+  return removed;
+}
+export function defineCompressedCache(options) {
+  const storage = options.storage ?? DEFAULT_STORAGE;
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const statusHeader = options.statusHeader ?? "x-cache";
+  const encodings = ENCODINGS.filter((encoding) => (options.encodings ?? ENCODINGS).includes(encoding));
+  if (!encodings.length) {
+    throw new Error("[compressed-cache] `encodings` needs at least one of br or gzip");
+  }
+  return defineMiddleware(async (event, next) => {
+    if (import.meta.dev || import.meta.prerender || event.req.method !== "GET" && event.req.method !== "HEAD") {
+      return next();
+    }
+    const { pathname, search } = event.url;
+    const payload = pathname.endsWith(PAYLOAD_SUFFIX);
+    const rule = options.rule({ pathname: pagePathname(pathname) });
+    if (!rule || rule.bypassCookies?.length && hasCookie({ cookieHeader: event.req.headers.get("cookie"), names: rule.bypassCookies })) {
+      return next();
+    }
+    const { query, extra, currentBuild } = normalizeQuery({ search, allowQuery: rule.allowQuery, payload, version: options.version });
+    const key = entryKey({ prefix, pathname, query });
+    const path = query ? `${pathname}?${query}` : pathname;
+    if (event.req.headers.get(REVALIDATE_HEADER) === REVALIDATE_TOKEN) {
+      const { response } = await renderPage({ event, next, storage, key, path, rule, encodings, config: options });
+      if (response && response.status < 500) {
+        await removeEntry({ storage, entry: key });
+      }
+      return response ?? new Response(null, { status: 204 });
+    }
+    const acceptEncoding = event.req.headers.get("accept-encoding");
+    const accepted = negotiateEncoding(acceptEncoding, encodings);
+    const source = accepted ?? encodings[0];
+    const target = accepted ?? negotiateEncoding(acceptEncoding);
+    const cached = await readPage({ storage, key, encoding: source });
+    if (cached && (payload || cached.meta.version === options.version)) {
+      const age = Date.now() - cached.meta.createdAt;
+      if (!cached.meta.expired && age <= rule.maxAge * 1e3) {
+        return sendPage({ event, page: cached, source, target, state: "HIT", statusHeader });
+      }
+      if (currentBuild && (rule.staleMaxAge === void 0 || rule.staleMaxAge > 0 && age <= (rule.maxAge + rule.staleMaxAge) * 1e3)) {
+        revalidate({ event, key, path });
+        return sendPage({ event, page: cached, source, target, state: "STALE", statusHeader });
+      }
+    }
+    if (extra || !currentBuild || event.req.method === "HEAD") {
+      return next();
+    }
+    const pending = inflight.get(key);
+    if (pending) {
+      const page = await pending ?? await readPage({ storage, key, encoding: source });
+      return page ? sendPage({ event, page, source, target, state: "MISS", statusHeader }) : next();
+    }
+    const task = renderPage({ event, next, storage, key, path, rule, encodings, config: options });
+    inflight.set(key, task.then(({ page }) => page, () => void 0));
+    try {
+      const { response, page } = await task;
+      return page ? sendPage({ event, page, source, target, state: "MISS", statusHeader }) : response;
+    } finally {
+      inflight.delete(key);
+    }
+  });
+}

package/dist/runtime/middleware.d.ts

@@ -0,0 +1,3 @@
+/** Caches every route that has a `compressedCache` route rule, using the module options from runtime config. */
+declare const _default: import("h3").Middleware;
+export default _default;

package/dist/runtime/middleware.js

@@ -0,0 +1,7 @@
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { defineCompressedCache } from "./compressed-cache.js";
+import { compressedCacheRule } from "./server-utils.js";
+export default defineCompressedCache({
+  ...useRuntimeConfig().compressedCache,
+  rule: compressedCacheRule
+});

package/dist/runtime/server-utils.d.ts

@@ -0,0 +1,35 @@
+import type { CompressedCacheRule } from './compressed-cache.js';
+type Target = {
+    path: string;
+} | {
+    pathPrefix: string;
+};
+/** The `compressedCache` route rule of a page pathname, from the app's current route rules. */
+export declare function compressedCacheRule({ pathname }: {
+    pathname: string;
+}): CompressedCacheRule | undefined;
+/**
+ * Marks cached copies stale, each is served once more while it re-renders in the background.
+ * `{ path: '/blog/post' }` for one page or `{ pathPrefix: '/blog/' }` for a section.
+ *
+ * @returns How many entries were expired.
+ */
+export declare function expireCompressedCache(target: Target): Promise<number>;
+/**
+ * Deletes cached copies, the next request renders fresh.
+ * `{ path: '/blog/post' }` for one page or `{ pathPrefix: '/blog/' }` for a section.
+ *
+ * @returns How many entries were removed.
+ */
+export declare function removeCompressedCache(target: Target): Promise<number>;
+/**
+ * Deletes entries past the `maxAge` (plus `staleMaxAge` when set) of their page's current route rule,
+ * and entries whose page no longer has a rule, on any storage driver.
+ * Pass `olderThan` (seconds) to delete by render age instead, for example `{ olderThan: 7 * 24 * 60 * 60 }`.
+ *
+ * @returns How many entries were removed.
+ */
+export declare function pruneCompressedCache({ olderThan }?: {
+    olderThan?: number;
+}): Promise<number>;
+export {};

package/dist/runtime/server-utils.js

@@ -0,0 +1,19 @@
+import { getRouteRules } from "nitro/app";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { expireCompressedCache as expire, pruneCompressedCache as prune, removeCompressedCache as remove } from "./compressed-cache.js";
+export function compressedCacheRule({ pathname }) {
+  return getRouteRules("GET", pathname).routeRules.compressedCache;
+}
+function location() {
+  const { storage, prefix } = useRuntimeConfig().compressedCache;
+  return { storage, prefix };
+}
+export function expireCompressedCache(target) {
+  return expire({ ...location(), ...target });
+}
+export function removeCompressedCache(target) {
+  return remove({ ...location(), ...target });
+}
+export function pruneCompressedCache({ olderThan } = {}) {
+  return olderThan === void 0 ? prune({ ...location(), rule: compressedCacheRule }) : prune({ ...location(), olderThan });
+}

package/dist/runtime/tasks/prune.d.ts

@@ -0,0 +1,3 @@
+/** Removes expired entries, or ones older than `cleanup.olderThan`, from the module's configured storage and prefix. */
+declare const _default: import("nitro/types").Task<number>;
+export default _default;

package/dist/runtime/tasks/prune.js

@@ -0,0 +1,10 @@
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { defineTask } from "nitro/task";
+import { pruneCompressedCache } from "../server-utils.js";
+export default defineTask({
+  meta: { name: "compressed-cache:prune", description: "Prune expired compressed cache entries" },
+  async run() {
+    const { cleanup } = useRuntimeConfig().compressedCache;
+    return { result: await pruneCompressedCache({ olderThan: cleanup.olderThan }) };
+  }
+});

package/dist/types.d.mts

@@ -0,0 +1,9 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'
+
+export { type CompressedCacheModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "nuxt-compressed-cache",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.1",
+  "description": "Serve Nuxt route rules from pre-compressed (brotli/gzip) cached copies, with stale-while-revalidate",
+  "author": "Manthankumar Satani",
+  "license": "MIT",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "nitro",
+    "cache",
+    "brotli",
+    "gzip",
+    "swr"
+  ],
+  "imports": {
+    "#src/*": "./src/*.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "nuxt": ">=5.0.0-0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "9.5.1",
+    "@nuxt/cli": "3.37.0",
+    "@nuxt/module-builder": "1.0.3",
+    "@nuxt/test-utils": "4.3.4",
+    "@types/node": "24.19.2",
+    "changelogen": "0.6.2",
+    "eslint": "10.13.0",
+    "nitro": "3.0.260903-beta",
+    "nuxt": "npm:nuxt-nightly@5.0.0-2610211357-d296167",
+    "typescript": "6.0.2",
+    "vitest": "5.0.5",
+    "vue": "3.5.44"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.15.0",
+      "onFail": "download"
+    }
+  },
+  "scripts": {
+    "dev": "nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "tsc --noEmit",
+    "release": "pnpm lint && pnpm test && pnpm test:types && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags"
+  }
 }