bun-serve-compress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rhuan Barreto
+
+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

@@ -0,0 +1,303 @@
+# bun-serve-compress
+
+Transparent HTTP response compression for `Bun.serve()` — gzip, brotli, and zstd.
+
+A drop-in replacement for `Bun.serve()` that automatically compresses responses based on the client's `Accept-Encoding` header. No middleware, no configuration required — just swap the import.
+
+## Why?
+
+Bun.serve() has no built-in response compression ([oven-sh/bun#2726](https://github.com/oven-sh/bun/issues/2726)). This library fills that gap with:
+
+- **Smart algorithm negotiation** — prefers zstd > brotli > gzip by default, respecting client `Accept-Encoding` quality weights
+- **Automatic skip logic** — images, fonts, video, already-compressed responses, small bodies, SSE, and `Cache-Control: no-transform` are never compressed
+- **Sane defaults** — brotli quality 5 (not 11, which is [~30x slower](https://cran.r-project.org/web/packages/brotli/vignettes/benchmarks.html)), gzip level 6, zstd level 3
+- **Zero config** — works out of the box, but fully customizable
+- **Bun-native** — uses `Bun.gzipSync()`, `Bun.zstdCompressSync()`, and `CompressionStream` for maximum performance; `node:zlib` brotliCompressSync for brotli (Bun has no native `Bun.brotliCompressSync()` yet)
+- **HTTP spec compliant** — correct `Vary`, `Content-Encoding`, `Content-Length`, ETag, and `Cache-Control: no-transform` handling
+
+## Install
+
+```bash
+bun add bun-serve-compress
+```
+
+## Quick Start
+
+```typescript
+import { serve } from "bun-serve-compress";
+
+serve({
+  port: 3000,
+  fetch(req) {
+    return new Response("Hello, World!");
+  },
+});
+```
+
+That's it. Responses are now compressed automatically.
+
+## Usage with Routes
+
+Works with Bun's route handlers, including HTML imports:
+
+```typescript
+import { serve } from "bun-serve-compress";
+import homepage from "./index.html";
+
+serve({
+  port: 3000,
+  routes: {
+    "/": homepage, // Bun's HTML bundling works transparently
+    "/api/data": () => Response.json({ message: "compressed automatically" }),
+    "/health": {
+      GET: () => new Response("ok"),
+    },
+  },
+  fetch(req) {
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```
+
+## Configuration
+
+Pass a `compression` option to customize behavior:
+
+```typescript
+import { serve } from "bun-serve-compress";
+
+serve({
+  port: 3000,
+  compression: {
+    // Algorithm preference order (default: ['zstd', 'br', 'gzip'])
+    algorithms: ["br", "gzip"],
+
+    // Minimum body size in bytes to compress (default: 1024)
+    minSize: 512,
+
+    // Per-algorithm settings
+    gzip: { level: 6 }, // 1-9 (default: 6)
+    brotli: { level: 5 }, // 0-11 (default: 5)
+    zstd: { level: 3 }, // 1-22 (default: 3)
+
+    // Additional MIME types to skip (merged with built-in list)
+    skipMimeTypes: ["application/x-custom-binary"],
+
+    // OR: override the entire skip list (replaces built-in list completely)
+    // overrideSkipMimeTypes: ["image/png", "application/zip"],
+
+    // Custom skip function (called after all other skip checks pass)
+    shouldCompress: (req, res) => {
+      // Return false to skip compression for this request/response
+      return !req.url.includes("/raw/");
+    },
+  },
+  fetch(req) {
+    return new Response("Hello!");
+  },
+});
+```
+
+### Disable compression entirely
+
+```typescript
+// Option 1: compression: false
+serve({
+  compression: false,
+  // ...
+});
+
+// Option 2: compression.disable
+serve({
+  compression: { disable: true },
+  // ...
+});
+```
+
+## What gets compressed?
+
+### Compressed (by default)
+
+- `text/*` (HTML, CSS, plain text, etc.)
+- `application/json`
+- `application/javascript`
+- `application/xml`
+- `image/svg+xml` (exception to image/\* skip — SVG is text-based)
+- Any response over 1KB without a matching skip rule
+
+### Skipped (by default)
+
+**By MIME type (prefix match):**
+
+- `image/*` (except `image/svg+xml`)
+- `audio/*`
+- `video/*`
+- `font/*`
+
+**By MIME type (exact match):**
+
+- `application/zip`, `application/gzip`, `application/x-gzip`
+- `application/x-bzip2`, `application/x-7z-compressed`, `application/x-rar-compressed`
+- `application/wasm`
+- `application/octet-stream`
+- `application/pdf`
+- `text/event-stream` (SSE — compression breaks chunked event delivery)
+
+**By HTTP semantics:**
+
+- Responses with existing `Content-Encoding` header (already compressed)
+- Responses with `Transfer-Encoding` containing a compression algorithm (gzip, deflate, br, zstd) — `Transfer-Encoding: chunked` alone does NOT skip
+- Responses with `Cache-Control: no-transform` (RFC 7234 §5.2.2.4 — intermediaries MUST NOT alter the representation)
+- Responses smaller than `minSize` (default: 1024 bytes)
+- Responses with no body (`null` body)
+- `204 No Content`, `304 Not Modified`, `101 Switching Protocols`
+- `HEAD` requests
+
+## HTTP Correctness
+
+The library handles HTTP semantics properly:
+
+- **`Content-Encoding`** is set to the chosen algorithm (`gzip`, `br`, or `zstd`)
+- **`Content-Length`** is updated to the compressed size (sync path) or removed (streaming path)
+- **`Vary: Accept-Encoding`** is appended when compression is considered — whether the response is compressed or not (for correct cache behavior). It is not added when compression is skipped entirely (e.g., images, HEAD requests)
+- **Strong ETags** are converted to weak ETags (`"abc"` → `W/"abc"`) when compressing, per RFC 7232 — the compressed body is a different representation
+- **Weak ETags** are preserved as-is (already weak)
+- **`Cache-Control: no-transform`** is respected — responses are passed through unmodified per RFC 7234
+- **Already-compressed responses** are never double-compressed (checked via `Content-Encoding` and `Transfer-Encoding` headers)
+- **Status codes** are preserved through compression (200, 201, 404, 500, etc.)
+- **Custom headers** are preserved through compression (X-Request-Id, etc.)
+
+## Algorithm Negotiation
+
+The library parses the client's `Accept-Encoding` header and selects the best algorithm:
+
+1. Parse each algorithm and its quality value (`q=`) from the header
+2. Filter to only algorithms the server supports (configurable via `algorithms` option)
+3. Handle wildcard `*` — gives unlisted supported algorithms the wildcard quality
+4. Handle `identity` — not a compression algorithm, ignored
+5. Handle `q=0` — explicit rejection of an algorithm
+6. Sort by client quality descending, then by server preference order as tiebreaker
+7. Return the best match, or `null` if no acceptable algorithm found
+
+Case-insensitive matching is supported (`GZIP`, `GZip`, `gzip` all work).
+
+## Compression Paths
+
+| Body type         | Strategy                                  | When                                                                              |
+| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |
+| Known size ≤ 10MB | Sync compression (`Bun.gzipSync`, etc.)   | Fastest path for typical responses                                                |
+| Unknown size      | Buffer → check minSize → sync compression | Catches small bodies without `Content-Length` (e.g., static `Response` in routes) |
+| Known size > 10MB | `CompressionStream` streaming             | Avoids buffering entire body in memory                                            |
+
+### Sync compression details
+
+| Algorithm | Implementation                                          | Notes                                            |
+| --------- | ------------------------------------------------------- | ------------------------------------------------ |
+| gzip      | `Bun.gzipSync(data, { level })`                         | Native Bun API                                   |
+| brotli    | `brotliCompressSync(data, { params })` from `node:zlib` | Bun has no native `Bun.brotliCompressSync()` yet |
+| zstd      | `Bun.zstdCompressSync(data, { level })`                 | Native Bun API                                   |
+
+### Streaming compression details
+
+All three algorithms use `CompressionStream` with Bun's extended format support:
+
+- gzip → `new CompressionStream("gzip")`
+- brotli → `new CompressionStream("brotli")` (Bun extension, not in Web standard)
+- zstd → `new CompressionStream("zstd")` (Bun extension, not in Web standard)
+
+## Route Type Support
+
+The library handles all Bun.serve() route value types:
+
+| Route value                                    | Behavior                                                                                                                   |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Response` object                              | Cloned and compressed per request (note: loses Bun's static route fast path — see [Known Limitations](#known-limitations)) |
+| Handler function `(req) => Response`           | Wrapped — response is compressed after handler returns                                                                     |
+| Method object `{ GET: fn, POST: fn }`          | Each method handler is wrapped individually                                                                                |
+| HTML import (`import page from './page.html'`) | Passed through to Bun's bundler pipeline untouched                                                                         |
+| `false`                                        | Passed through — Bun falls through to the `fetch` handler                                                                  |
+| `null` / `undefined`                           | Passed through as-is                                                                                                       |
+
+## Exported Utilities
+
+The library exports its internal utilities for advanced use cases:
+
+```typescript
+import {
+  serve, // Drop-in Bun.serve() replacement
+  negotiate, // Parse Accept-Encoding → best algorithm
+  shouldSkip, // Check if compression should be skipped
+  compress, // Compress a Response object
+  addVaryHeader, // Add Vary: Accept-Encoding to a Response
+} from "bun-serve-compress";
+
+// Types
+import type {
+  CompressionAlgorithm, // "zstd" | "br" | "gzip"
+  CompressionOptions, // User-facing config
+  AlgorithmOptions, // Per-algorithm { level } config
+  ResolvedCompressionOptions, // Fully resolved config with defaults
+} from "bun-serve-compress";
+```
+
+## Testing
+
+208 tests covering negotiation, skip logic, compression integrity, HTTP semantics, concurrency, large body integrity, Bun-specific compatibility, and version guard. Run with:
+
+```bash
+bun test
+```
+
+### Test suite inspirations
+
+The test suite was designed by studying the test suites of established HTTP compression implementations to ensure comprehensive coverage:
+
+| Library / Server             | What we learned                                                                                                                                                   | Link                                                                                                                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Express/compression**      | `Cache-Control: no-transform` (RFC 7234), Vary header semantics, ETag weak/strong handling, threshold behavior, empty body edge cases, quality weight negotiation | [test/compression.js](https://github.com/expressjs/compression/blob/master/test/compression.js)                                                                            |
+| **Fastify/fastify-compress** | Case-insensitive Accept-Encoding, Content-Type with charset/boundary params, missing Content-Type, custom header preservation, algorithm restriction              | [test/global-compress.test.js](https://github.com/fastify/fastify-compress/blob/master/test/global-compress.test.js)                                                       |
+| **Koa/compress**             | Unknown algorithm handling (sdch), custom shouldCompress, SVG exception for image/\* skip, default/fallback encoding                                              | [test/index.test.ts](https://github.com/koajs/compress/blob/master/test/index.test.ts)                                                                                     |
+| **Go net/http gziphandler**  | Threshold boundary conditions (exact size, off-by-one), parallel compression benchmarks, large body integrity, Accept-Encoding: identity                          | [gzip_test.go](https://github.com/nytimes/gziphandler/blob/master/gzip_test.go)                                                                                            |
+| **Nginx gzip module**        | Transfer-Encoding already set, MIME type prefix matching, no-transform directive                                                                                  | [ngx_http_gzip_module docs](https://nginx.org/en/docs/http/ngx_http_gzip_module.html)                                                                                      |
+| **Hono compress**            | Cache-Control no-transform, Transfer-Encoding checks, identity encoding handling                                                                                  | [compress/index.test.ts](https://github.com/honojs/hono/blob/main/src/middleware/compress/index.test.ts)                                                                   |
+| **Bun test suite**           | Static route cloning, fetch auto-decompression, CompressionStream formats, empty body regression, double-compression prevention                                   | [test/regression/issue/](https://github.com/oven-sh/bun/tree/main/test/regression/issue), [test/js/web/fetch/](https://github.com/oven-sh/bun/tree/main/test/js/web/fetch) |
+
+Each test file includes a detailed header comment documenting which specific test cases came from which source.
+
+## Known Limitations
+
+### Static route performance trade-off
+
+When using static `Response` objects in routes (e.g., `"/": new Response("hello")`), Bun normally serves them via an optimized fast path that bypasses the JS event loop entirely. This library converts static routes into handler functions (to clone and compress per-request), which loses that optimization. For most applications this is negligible — the compression savings far outweigh the routing overhead.
+
+### Future Bun auto-compression
+
+Bun's HTTP server has a [TODO comment](https://github.com/oven-sh/bun/issues/2726) to add built-in compression. If/when Bun adds native auto-compression to `Bun.serve()`, this library could cause double-compression. We will update the library to detect and respect any future Bun compression flag. Monitor issue [#2726](https://github.com/oven-sh/bun/issues/2726) for updates.
+
+### Bun's fetch() auto-decompression
+
+Bun's `fetch()` client **automatically decompresses** responses and **strips the `Content-Encoding` header**. If you need to verify compression is working in your own tests or debugging, use `fetch(url, { decompress: false })` — this is a Bun-specific option that preserves the raw compressed response.
+
+### Streaming compression quality
+
+The `CompressionStream` API (used for bodies > 10MB) does not accept quality/level parameters for all formats. For the sync path (≤ 10MB), compression levels are fully configurable. For most real-world responses, the sync path is used.
+
+## Requirements
+
+- **Bun ≥ 1.3.3** (for `CompressionStream` with zstd support)
+
+The library checks `Bun.version` on import and throws a clear error if the runtime is unsupported:
+
+```
+bun-serve-compress requires Bun >= 1.3.3, but you are running Bun 1.2.0. Please upgrade Bun: bun upgrade
+```
+
+If loaded outside of Bun (e.g., Node.js), it throws:
+
+```
+bun-serve-compress requires the Bun runtime. This library uses Bun-specific APIs (Bun.serve, Bun.gzipSync, CompressionStream with zstd) and cannot run in Node.js or other runtimes.
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "bun-serve-compress",
+  "version": "0.1.0",
+  "description": "Transparent HTTP response compression for Bun.serve() — gzip, brotli, zstd",
+  "keywords": [
+    "accept-encoding",
+    "brotli",
+    "bun",
+    "bun-serve",
+    "compression",
+    "content-encoding",
+    "gzip",
+    "http",
+    "serve",
+    "server",
+    "zstd"
+  ],
+  "homepage": "https://github.com/rhuanbarreto/bun-serve-compress#readme",
+  "bugs": {
+    "url": "https://github.com/rhuanbarreto/bun-serve-compress/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rhuanbarreto/bun-serve-compress"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit",
+    "check": "oxlint && oxfmt --check && tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.9",
+    "elysia": "^1.4.28",
+    "hono": "^4.12.8",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
+    "typescript": "^5.7"
+  },
+  "engines": {
+    "bun": ">=1.3.3"
+  }
+}

package/src/compress.ts

@@ -0,0 +1,207 @@
+import { brotliCompressSync, constants as zlibConstants } from "node:zlib";
+import type { CompressionAlgorithm, ResolvedCompressionOptions } from "./types";
+
+/**
+ * Compress data synchronously using the specified algorithm.
+ *
+ * Uses Bun's native sync compression functions for gzip and zstd,
+ * and node:zlib's brotliCompressSync for brotli (Bun has no native
+ * Bun.brotliCompressSync yet).
+ */
+function compressSync(
+  data: Uint8Array<ArrayBuffer>,
+  algorithm: CompressionAlgorithm,
+  config: ResolvedCompressionOptions,
+): Uint8Array<ArrayBuffer> {
+  switch (algorithm) {
+    case "gzip":
+      return Bun.gzipSync(data, { level: config.gzip.level as any }) as Uint8Array<ArrayBuffer>;
+
+    case "br": {
+      const compressed = brotliCompressSync(data, {
+        params: {
+          [zlibConstants.BROTLI_PARAM_QUALITY]: config.brotli.level,
+        },
+      });
+      return new Uint8Array(
+        compressed.buffer,
+        compressed.byteOffset,
+        compressed.byteLength,
+      ) as Uint8Array<ArrayBuffer>;
+    }
+
+    case "zstd":
+      return Bun.zstdCompressSync(data, { level: config.zstd.level }) as Uint8Array<ArrayBuffer>;
+  }
+}
+
+/**
+ * Create a compressed ReadableStream using CompressionStream API.
+ */
+function compressStream(body: ReadableStream, algorithm: CompressionAlgorithm): ReadableStream {
+  // Map algorithm names to CompressionStream format
+  let format: string;
+  switch (algorithm) {
+    case "gzip":
+      format = "gzip";
+      break;
+    case "br":
+      // Bun supports "brotli" as a custom format name in CompressionStream
+      format = "brotli";
+      break;
+    case "zstd":
+      format = "zstd";
+      break;
+  }
+
+  const stream = new CompressionStream(format as CompressionFormat);
+  return body.pipeThrough(stream as any);
+}
+
+/**
+ * Append a value to the Vary header, preserving existing values.
+ */
+function appendVary(headers: Headers, value: string): void {
+  const existing = headers.get("vary");
+  if (existing) {
+    // Don't add if already present or if Vary is *
+    if (existing === "*") return;
+    const values = existing.split(",").map((v) => v.trim().toLowerCase());
+    if (values.includes(value.toLowerCase())) return;
+    headers.set("vary", `${existing}, ${value}`);
+  } else {
+    headers.set("vary", value);
+  }
+}
+
+/**
+ * Build response headers for a compressed response.
+ */
+function buildHeaders(
+  original: Headers,
+  algorithm: CompressionAlgorithm,
+  compressedSize: number | null,
+): Headers {
+  const headers = new Headers(original);
+
+  // Set Content-Encoding
+  headers.set("content-encoding", algorithm);
+
+  // Update or remove Content-Length
+  if (compressedSize !== null) {
+    headers.set("content-length", compressedSize.toString());
+  } else {
+    headers.delete("content-length");
+  }
+
+  // Append Vary: Accept-Encoding
+  appendVary(headers, "Accept-Encoding");
+
+  // Handle ETag — if present and strong, make it weak since body changed
+  const etag = headers.get("etag");
+  if (etag && !etag.startsWith("W/")) {
+    headers.set("etag", `W/${etag}`);
+  }
+
+  return headers;
+}
+
+/**
+ * Compress an HTTP Response.
+ *
+ * Chooses between sync (buffered) and streaming compression based on the response body type:
+ * - If the body can be read as an ArrayBuffer (non-streaming), use sync compression
+ * - If the body is a ReadableStream, use CompressionStream
+ *
+ * Also performs a final minSize check after buffering — this catches cases where
+ * Content-Length was not set on the original response (e.g., static Route responses).
+ *
+ * Returns a new Response with compressed body and updated headers.
+ */
+export async function compress(
+  res: Response,
+  algorithm: CompressionAlgorithm,
+  config: ResolvedCompressionOptions,
+): Promise<Response> {
+  // Check if we should use streaming or buffered compression
+  // If bodyUsed is true, we can't read it — shouldn't happen but guard against it
+  if (res.bodyUsed) return res;
+
+  const body = res.body;
+  if (!body) return res;
+
+  // Try buffered (sync) compression first — faster for small/medium responses
+  // We check if we can read the full body. If Content-Length is known and reasonable
+  // (< 10MB), use sync. Otherwise use streaming.
+  const contentLength = res.headers.get("content-length");
+  const knownSize = contentLength ? parseInt(contentLength, 10) : null;
+  const MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10MB
+
+  if (knownSize !== null && knownSize <= MAX_BUFFER_SIZE) {
+    // Known size, fits in memory — sync path
+    const buffer = new Uint8Array(await res.arrayBuffer()) as Uint8Array<ArrayBuffer>;
+    const compressed = compressSync(buffer, algorithm, config);
+
+    return new Response(compressed as BodyInit, {
+      status: res.status,
+      statusText: res.statusText,
+      headers: buildHeaders(res.headers, algorithm, compressed.byteLength),
+    });
+  }
+
+  if (knownSize !== null) {
+    // Known size but too large — streaming path
+    const compressedStream = compressStream(body, algorithm);
+
+    return new Response(compressedStream, {
+      status: res.status,
+      statusText: res.statusText,
+      headers: buildHeaders(res.headers, algorithm, null),
+    });
+  }
+
+  // Unknown size (no Content-Length) — buffer to check minSize, then compress
+  // This handles static Response objects that don't set Content-Length
+  const buffer = new Uint8Array(await res.arrayBuffer()) as Uint8Array<ArrayBuffer>;
+
+  if (buffer.byteLength < config.minSize) {
+    // Below threshold — return uncompressed with original body
+    return new Response(buffer as BodyInit, {
+      status: res.status,
+      statusText: res.statusText,
+      headers: new Headers(res.headers),
+    });
+  }
+
+  const compressed = compressSync(buffer, algorithm, config);
+
+  return new Response(compressed as BodyInit, {
+    status: res.status,
+    statusText: res.statusText,
+    headers: buildHeaders(res.headers, algorithm, compressed.byteLength),
+  });
+}
+
+/**
+ * Add Vary: Accept-Encoding header to a response without compressing it.
+ * Used when we skip compression but still need correct caching behavior.
+ */
+export function addVaryHeader(res: Response): Response {
+  // If the response already has the correct Vary header, return as-is
+  const vary = res.headers.get("vary");
+  if (vary) {
+    if (vary === "*") return res;
+    const values = vary.split(",").map((v) => v.trim().toLowerCase());
+    if (values.includes("accept-encoding")) return res;
+  }
+
+  // Clone headers and add Vary
+  const headers = new Headers(res.headers);
+  appendVary(headers, "Accept-Encoding");
+
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
+}

package/src/constants.ts

@@ -0,0 +1,79 @@
+import type { CompressionAlgorithm, ResolvedCompressionOptions } from "./types";
+
+/**
+ * Default algorithm preference order.
+ * zstd is fastest with best ratio, brotli has great ratio, gzip is universal fallback.
+ */
+export const DEFAULT_ALGORITHMS: CompressionAlgorithm[] = ["zstd", "br", "gzip"];
+
+/** Default compression levels per algorithm */
+export const DEFAULT_GZIP_LEVEL = 6;
+export const DEFAULT_BROTLI_LEVEL = 5; // NOT 11 — max quality is ~30x slower
+export const DEFAULT_ZSTD_LEVEL = 3;
+
+/** Minimum response size in bytes to trigger compression */
+export const DEFAULT_MIN_SIZE = 1024;
+
+/**
+ * MIME types that should NOT be compressed (exact matches).
+ * These are already compressed or binary formats where compression adds overhead.
+ */
+export const SKIP_MIME_TYPES = new Set<string>([
+  // Archives (already compressed)
+  "application/zip",
+  "application/gzip",
+  "application/x-gzip",
+  "application/x-bzip2",
+  "application/x-7z-compressed",
+  "application/x-rar-compressed",
+
+  // Binary formats
+  "application/wasm",
+  "application/octet-stream",
+  "application/pdf",
+
+  // SSE — compression breaks chunked event delivery
+  "text/event-stream",
+]);
+
+/**
+ * MIME type prefixes that should NOT be compressed.
+ * Entire categories of binary/compressed content.
+ */
+export const SKIP_MIME_PREFIXES: string[] = [
+  "image/", // except image/svg+xml — handled specially
+  "audio/",
+  "video/",
+  "font/",
+];
+
+/**
+ * MIME types that are exceptions to the prefix skip rules.
+ * These are text-based formats within otherwise-binary categories.
+ */
+export const COMPRESSIBLE_EXCEPTIONS = new Set<string>(["image/svg+xml"]);
+
+/**
+ * HTTP status codes that indicate no body — skip compression.
+ */
+export const NO_BODY_STATUSES = new Set<number>([
+  101, // Switching Protocols (WebSocket)
+  204, // No Content
+  304, // Not Modified
+]);
+
+/**
+ * Build the default resolved config.
+ */
+export function getDefaultResolvedConfig(): ResolvedCompressionOptions {
+  return {
+    disable: false,
+    algorithms: [...DEFAULT_ALGORITHMS],
+    gzip: { level: DEFAULT_GZIP_LEVEL },
+    brotli: { level: DEFAULT_BROTLI_LEVEL },
+    zstd: { level: DEFAULT_ZSTD_LEVEL },
+    minSize: DEFAULT_MIN_SIZE,
+    skipMimeTypes: new Set(SKIP_MIME_TYPES),
+    skipMimePrefixes: [...SKIP_MIME_PREFIXES],
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { serve } from "./serve";
+export { negotiate } from "./negotiate";
+export { shouldSkip } from "./skip";
+export { compress, addVaryHeader } from "./compress";
+export type {
+  CompressionAlgorithm,
+  CompressionOptions,
+  AlgorithmOptions,
+  ResolvedCompressionOptions,
+} from "./types";

package/src/negotiate.ts

@@ -0,0 +1,106 @@
+import type { CompressionAlgorithm } from "./types";
+
+interface EncodingEntry {
+  algorithm: string;
+  quality: number;
+}
+
+/**
+ * Parse an Accept-Encoding header into entries with quality values.
+ *
+ * Examples:
+ *   "gzip, br;q=0.8, zstd;q=1.0" → [{algorithm:"gzip",quality:1}, {algorithm:"br",quality:0.8}, {algorithm:"zstd",quality:1}]
+ *   "*;q=0.5" → [{algorithm:"*",quality:0.5}]
+ */
+function parseAcceptEncoding(header: string): EncodingEntry[] {
+  const entries: EncodingEntry[] = [];
+
+  for (const part of header.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    const [algorithm, ...params] = trimmed.split(";").map((s) => s.trim());
+    let quality = 1.0;
+
+    for (const param of params) {
+      const match = param.match(/^q\s*=\s*([0-9.]+)$/i);
+      if (match) {
+        quality = parseFloat(match[1]);
+        if (isNaN(quality)) quality = 1.0;
+        quality = Math.max(0, Math.min(1, quality));
+      }
+    }
+
+    entries.push({ algorithm: algorithm.toLowerCase(), quality });
+  }
+
+  return entries;
+}
+
+/**
+ * Negotiate the best compression algorithm based on the Accept-Encoding header
+ * and the server's preferred algorithm order.
+ *
+ * Returns the chosen algorithm, or null if no acceptable algorithm is found.
+ *
+ * Selection logic:
+ * 1. Parse client's Accept-Encoding into {algorithm, quality} pairs
+ * 2. Filter to only algorithms we support and the client accepts (q > 0)
+ * 3. Handle wildcard (*) — gives unlisted supported algorithms the wildcard quality
+ * 4. Sort by client quality descending, then by server preference order
+ * 5. Return the top result
+ */
+export function negotiate(
+  acceptEncoding: string,
+  preferredOrder: CompressionAlgorithm[],
+): CompressionAlgorithm | null {
+  if (!acceptEncoding) return null;
+
+  const entries = parseAcceptEncoding(acceptEncoding);
+  if (entries.length === 0) return null;
+
+  // Build a map of algorithm → quality from client preferences
+  const clientPrefs = new Map<string, number>();
+  let wildcardQuality: number | null = null;
+
+  for (const entry of entries) {
+    if (entry.algorithm === "*") {
+      wildcardQuality = entry.quality;
+    } else {
+      clientPrefs.set(entry.algorithm, entry.quality);
+    }
+  }
+
+  // Build candidates: supported algorithms that the client accepts
+  const candidates: { algorithm: CompressionAlgorithm; quality: number; serverRank: number }[] = [];
+
+  for (let i = 0; i < preferredOrder.length; i++) {
+    const algo = preferredOrder[i];
+
+    let quality: number | null = null;
+    if (clientPrefs.has(algo)) {
+      quality = clientPrefs.get(algo)!;
+    } else if (wildcardQuality !== null) {
+      quality = wildcardQuality;
+    }
+
+    // Skip if client doesn't accept this algorithm or explicitly rejects it (q=0)
+    if (quality === null || quality === 0) continue;
+
+    candidates.push({
+      algorithm: algo,
+      quality,
+      serverRank: i,
+    });
+  }
+
+  if (candidates.length === 0) return null;
+
+  // Sort: highest quality first, then by server preference order (lower rank = more preferred)
+  candidates.sort((a, b) => {
+    if (a.quality !== b.quality) return b.quality - a.quality;
+    return a.serverRank - b.serverRank;
+  });
+
+  return candidates[0].algorithm;
+}

package/src/serve.ts

@@ -0,0 +1,267 @@
+import { getDefaultResolvedConfig, SKIP_MIME_TYPES } from "./constants";
+import { compress, addVaryHeader } from "./compress";
+import { negotiate } from "./negotiate";
+import { shouldSkip } from "./skip";
+import type { CompressionOptions, ResolvedCompressionOptions } from "./types";
+
+/**
+ * Minimum supported Bun version (semver range).
+ * Requires Bun >= 1.3.3 for CompressionStream with zstd support.
+ */
+const MIN_BUN_VERSION_RANGE = ">=1.3.3";
+const MIN_BUN_VERSION_DISPLAY = "1.3.3";
+
+/**
+ * Check that the current Bun version meets the minimum requirement.
+ * Uses Bun's built-in semver utility for reliable version comparison.
+ * Throws a clear error if not.
+ */
+function checkBunVersion(): void {
+  if (typeof Bun === "undefined" || !Bun.version) {
+    throw new Error(
+      "bun-serve-compress requires the Bun runtime. " +
+        "This library uses Bun-specific APIs (Bun.serve, Bun.gzipSync, CompressionStream with zstd) " +
+        "and cannot run in Node.js or other runtimes.",
+    );
+  }
+
+  if (!Bun.semver.satisfies(Bun.version, MIN_BUN_VERSION_RANGE)) {
+    throw new Error(
+      `bun-serve-compress requires Bun >= ${MIN_BUN_VERSION_DISPLAY}, but you are running Bun ${Bun.version}. ` +
+        "Please upgrade Bun: bun upgrade",
+    );
+  }
+}
+
+// Run version check on module load
+checkBunVersion();
+
+/**
+ * Resolve user-provided compression options into a fully-populated config
+ * with all defaults applied.
+ */
+function resolveConfig(options?: CompressionOptions | false): ResolvedCompressionOptions {
+  const defaults = getDefaultResolvedConfig();
+
+  if (options === false || options?.disable) {
+    return { ...defaults, disable: true };
+  }
+
+  if (!options) return defaults;
+
+  const config: ResolvedCompressionOptions = {
+    disable: false,
+    algorithms: options.algorithms ?? defaults.algorithms,
+    gzip: { level: options.gzip?.level ?? defaults.gzip.level },
+    brotli: { level: options.brotli?.level ?? defaults.brotli.level },
+    zstd: { level: options.zstd?.level ?? defaults.zstd.level },
+    minSize: options.minSize ?? defaults.minSize,
+    skipMimeTypes: defaults.skipMimeTypes,
+    skipMimePrefixes: defaults.skipMimePrefixes,
+    shouldCompress: options.shouldCompress,
+  };
+
+  // Handle custom skip MIME types
+  if (options.overrideSkipMimeTypes) {
+    config.skipMimeTypes = new Set(options.overrideSkipMimeTypes);
+    config.skipMimePrefixes = []; // user took full control
+  } else if (options.skipMimeTypes) {
+    // Merge with defaults
+    config.skipMimeTypes = new Set([...SKIP_MIME_TYPES, ...options.skipMimeTypes]);
+  }
+
+  return config;
+}
+
+/**
+ * The compression middleware logic applied to each response.
+ */
+function compressResponse(
+  req: Request,
+  res: Response,
+  config: ResolvedCompressionOptions,
+): Response | Promise<Response> {
+  // Check if compression should be skipped
+  if (shouldSkip(req, res, config)) {
+    return res;
+  }
+
+  // Negotiate the best algorithm
+  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
+  const algorithm = negotiate(acceptEncoding, config.algorithms);
+
+  if (!algorithm) {
+    // No acceptable algorithm, but add Vary header for caching
+    return addVaryHeader(res);
+  }
+
+  // Compress the response
+  return compress(res, algorithm, config);
+}
+
+/**
+ * Wrap a fetch handler to add compression.
+ */
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
+
+// eslint-disable-next-line typescript/ban-types, typescript/no-unsafe-function-type -- Bun's fetch handler type is complex
+type AnyFunction = Function;
+
+function wrapFetch(originalFetch: AnyFunction, config: ResolvedCompressionOptions): AnyFunction {
+  return async function (this: any, req: Request, server: any) {
+    const response = await originalFetch.call(this, req, server);
+
+    // WebSocket upgrade or void return — pass through
+    if (!response) return response;
+
+    return compressResponse(req, response as Response, config);
+  };
+}
+
+/**
+ * Wrap route handlers to add compression.
+ *
+ * Routes can be:
+ * - Response objects (static)
+ * - Handler functions (req => Response)
+ * - HTML imports (special Bun objects — pass through untouched)
+ * - Method-specific objects { GET: handler, POST: handler }
+ */
+function wrapRoutes(
+  routes: Record<string, any>,
+  config: ResolvedCompressionOptions,
+): Record<string, any> {
+  const wrapped: Record<string, any> = {};
+
+  for (const [path, handler] of Object.entries(routes)) {
+    wrapped[path] = wrapRouteHandler(handler, config);
+  }
+
+  return wrapped;
+}
+
+/**
+ * Wrap a single route handler.
+ */
+function wrapRouteHandler(handler: any, config: ResolvedCompressionOptions): any {
+  // false: Bun falls through to the fetch handler. Pass through as-is.
+  // null/undefined: no handler. Pass through as-is.
+  if (handler === false || handler === null || handler === undefined) {
+    return handler;
+  }
+
+  // HTML import — Bun handles these specially for frontend bundling.
+  // They are objects with specific internal properties that Bun's serve recognizes.
+  // We must NOT wrap these — let Bun handle them natively.
+  // HTML imports are typically objects (not Response, not Function) that Bun processes
+  // into its asset pipeline. We detect them by checking they're not a standard type.
+  if (isHtmlImport(handler)) {
+    return handler;
+  }
+
+  // Response object (static route) — wrap in a function that clones and compresses per request
+  if (handler instanceof Response) {
+    return function (req: Request) {
+      const cloned = handler.clone();
+      return compressResponse(req, cloned, config);
+    };
+  }
+
+  // Handler function
+  if (typeof handler === "function") {
+    return async function (this: any, req: Request, server: any) {
+      const response = await handler.call(this, req, server);
+      if (!response) return response;
+      return compressResponse(req, response, config);
+    };
+  }
+
+  // Method-specific object: { GET: handler, POST: handler, ... }
+  if (typeof handler === "object" && !Array.isArray(handler)) {
+    const hasMethodKey = Object.keys(handler).some((key) => HTTP_METHODS.has(key.toUpperCase()));
+
+    if (hasMethodKey) {
+      const wrappedMethods: Record<string, any> = {};
+      for (const [method, methodHandler] of Object.entries(handler)) {
+        wrappedMethods[method] = wrapRouteHandler(methodHandler, config);
+      }
+      return wrappedMethods;
+    }
+  }
+
+  // Unknown type — pass through unchanged (let Bun handle or error)
+  return handler;
+}
+
+/**
+ * Detect if a route handler is an HTML import (Bun's frontend bundling feature).
+ *
+ * When you do `import page from './page.html'` in Bun, it creates a special
+ * module object that Bun.serve() recognizes for its built-in bundler pipeline.
+ * These are NOT Response objects or functions — they're opaque module objects.
+ *
+ * We must pass these through untouched so Bun's asset pipeline works correctly.
+ */
+function isHtmlImport(handler: any): boolean {
+  // HTML imports are not Response, not Function, not null/undefined
+  // They are objects that Bun's serve() knows how to handle internally.
+  // The safest detection: it's an object with a default export or
+  // is a module namespace object from an HTML import.
+  if (typeof handler !== "object") return false;
+  if (handler instanceof Response) return false;
+  if (handler instanceof ReadableStream) return false;
+  if (Array.isArray(handler)) return false;
+
+  // Check for Bun's HTML module marker
+  // HTML imports have a specific shape — they're typically the module itself
+  // with properties that Bun uses internally for bundling
+  // A method-specific handler would have HTTP method keys (GET, POST, etc.)
+  const keys = Object.keys(handler);
+  const hasMethodKey = keys.some((key) => HTTP_METHODS.has(key.toUpperCase()));
+  if (hasMethodKey) return false;
+
+  // If it's an object without HTTP method keys, it's likely an HTML import
+  // or some other Bun-specific handler — pass through
+  return true;
+}
+
+/**
+ * Drop-in replacement for Bun.serve() that adds transparent response compression.
+ *
+ * Usage:
+ * ```ts
+ * import { serve } from 'bun-serve-compress';
+ *
+ * serve({
+ *   port: 3000,
+ *   compression: { algorithms: ['zstd', 'br', 'gzip'] },
+ *   fetch(req) {
+ *     return new Response('Hello!');
+ *   },
+ * });
+ * ```
+ */
+export function serve(options: any): any {
+  // Extract compression config
+  const { compression, ...serveOptions } = options;
+
+  // Resolve config with defaults
+  const config = resolveConfig(compression);
+
+  // If compression is disabled, just pass through to Bun.serve
+  if (config.disable) {
+    return Bun.serve(serveOptions);
+  }
+
+  // Wrap fetch handler if present
+  if (serveOptions.fetch) {
+    serveOptions.fetch = wrapFetch(serveOptions.fetch, config);
+  }
+
+  // Wrap routes if present
+  if (serveOptions.routes) {
+    serveOptions.routes = wrapRoutes(serveOptions.routes, config);
+  }
+
+  return Bun.serve(serveOptions);
+}

package/src/skip.ts

@@ -0,0 +1,117 @@
+import { COMPRESSIBLE_EXCEPTIONS, NO_BODY_STATUSES } from "./constants";
+import type { ResolvedCompressionOptions } from "./types";
+
+/**
+ * Extract the MIME type from a Content-Type header value.
+ * Strips parameters like charset, boundary, etc.
+ *
+ * "text/html; charset=utf-8" → "text/html"
+ */
+function extractMimeType(contentType: string): string {
+  return contentType.split(";")[0].trim().toLowerCase();
+}
+
+/**
+ * Check if a MIME type matches the skip list.
+ */
+function mimeMatchesSkipList(
+  mime: string,
+  skipTypes: Set<string>,
+  skipPrefixes: string[],
+): boolean {
+  // Exceptions first — these are compressible despite matching prefix rules
+  // (e.g., image/svg+xml is text-based despite the image/* prefix skip)
+  if (COMPRESSIBLE_EXCEPTIONS.has(mime)) return false;
+
+  // Exact match
+  if (skipTypes.has(mime)) return true;
+
+  // Prefix match (e.g., "image/", "audio/")
+  for (const prefix of skipPrefixes) {
+    if (mime.startsWith(prefix)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if Cache-Control header contains the no-transform directive.
+ * Per RFC 7234 Section 5.2.2.4, intermediaries MUST NOT alter the
+ * representation when no-transform is present.
+ */
+function hasNoTransform(res: Response): boolean {
+  const cacheControl = res.headers.get("cache-control");
+  if (!cacheControl) return false;
+  return cacheControl
+    .split(",")
+    .some((directive) => directive.trim().toLowerCase() === "no-transform");
+}
+
+/**
+ * Determine whether compression should be skipped for this request/response pair.
+ *
+ * Returns true if compression should be SKIPPED (response passed through as-is).
+ */
+export function shouldSkip(
+  req: Request,
+  res: Response,
+  config: ResolvedCompressionOptions,
+): boolean {
+  // 1. Compression disabled globally
+  if (config.disable) return true;
+
+  // 2. HEAD requests have no body to compress
+  if (req.method === "HEAD") return true;
+
+  // 3. Status codes that indicate no body
+  if (NO_BODY_STATUSES.has(res.status)) return true;
+
+  // 4. Response already has Content-Encoding (already compressed)
+  if (res.headers.has("content-encoding")) return true;
+
+  // 5. Response already has Transfer-Encoding set (already encoded)
+  const transferEncoding = res.headers.get("transfer-encoding");
+  if (transferEncoding) {
+    const encodings = transferEncoding.toLowerCase();
+    // Skip if there's a content encoding like deflate or gzip in Transfer-Encoding
+    // (chunked alone is fine — it's just framing)
+    if (
+      encodings.includes("gzip") ||
+      encodings.includes("deflate") ||
+      encodings.includes("compress") ||
+      encodings.includes("br") ||
+      encodings.includes("zstd")
+    ) {
+      return true;
+    }
+  }
+
+  // 6. Cache-Control: no-transform — MUST NOT alter representation (RFC 7234)
+  if (hasNoTransform(res)) return true;
+
+  // 7. No body
+  if (res.body === null) return true;
+
+  // 8. Check Content-Type against skip list
+  const contentType = res.headers.get("content-type");
+  if (contentType) {
+    const mime = extractMimeType(contentType);
+    if (mimeMatchesSkipList(mime, config.skipMimeTypes, config.skipMimePrefixes)) {
+      return true;
+    }
+  }
+
+  // 9. Body size below minimum threshold (only if Content-Length is known)
+  const contentLength = res.headers.get("content-length");
+  if (contentLength !== null) {
+    const size = parseInt(contentLength, 10);
+    if (!isNaN(size) && size < config.minSize) return true;
+  }
+
+  // 10. User's custom shouldCompress function
+  if (config.shouldCompress && !config.shouldCompress(req, res)) {
+    return true;
+  }
+
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Supported compression algorithms.
+ * Names match the Accept-Encoding header values.
+ */
+export type CompressionAlgorithm = "zstd" | "br" | "gzip";
+
+/**
+ * Per-algorithm quality/level settings.
+ */
+export interface AlgorithmOptions {
+  /**
+   * Compression level.
+   * - gzip: 1-9 (default 6)
+   * - brotli: 0-11 (default 5, NOT 11 which is too slow for real-time)
+   * - zstd: 1-22 (default 3)
+   */
+  level?: number;
+}
+
+/**
+ * Compression configuration options.
+ */
+export interface CompressionOptions {
+  /** Disable compression entirely. Default: false */
+  disable?: boolean;
+
+  /** Algorithm preference order. Default: ['zstd', 'br', 'gzip'] */
+  algorithms?: CompressionAlgorithm[];
+
+  /** Per-algorithm settings */
+  gzip?: AlgorithmOptions;
+  brotli?: AlgorithmOptions;
+  zstd?: AlgorithmOptions;
+
+  /** Minimum response body size in bytes to compress. Default: 1024 */
+  minSize?: number;
+
+  /** Additional MIME types to skip (merged with built-in skip list) */
+  skipMimeTypes?: string[];
+
+  /** Override the entire skip list instead of merging with built-in list */
+  overrideSkipMimeTypes?: string[];
+
+  /**
+   * Custom function to decide whether to compress a response.
+   * Return true to compress, false to skip.
+   * Called after all other skip checks pass.
+   */
+  shouldCompress?: (req: Request, res: Response) => boolean;
+}
+
+/**
+ * Resolved compression config with all defaults applied.
+ * All fields are guaranteed to be present.
+ */
+export interface ResolvedCompressionOptions {
+  disable: boolean;
+  algorithms: CompressionAlgorithm[];
+  gzip: Required<AlgorithmOptions>;
+  brotli: Required<AlgorithmOptions>;
+  zstd: Required<AlgorithmOptions>;
+  minSize: number;
+  skipMimeTypes: Set<string>;
+  skipMimePrefixes: string[];
+  shouldCompress?: (req: Request, res: Response) => boolean;
+}