@stacksjs/bun-router 0.0.23 → 0.0.25

package/dist/cli.js

@@ -2047,7 +2047,7 @@ function getPrefix() {
 }
 var prefix = getPrefix();
 // package.json
-var version = "0.0.23";
+var version = "0.0.25";
 
 // src/cli/middleware.ts
 import fs2 from "fs/promises";

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * as Errors from './errors';
 export * from './middleware';
 export { enableRequestContext, getCurrentRequest, request, runWithRequest, setCurrentRequest } from './request/context';
 export * from './session';
+export * from './response/compression';
 export * from './response/response-factory';
 export * from './router';
 export { MiddlewareGroupRegistry, middlewareGroups } from './router/middleware-groups';

package/dist/index.js

@@ -2047,6 +2047,91 @@ function request() {
   }
   return req;
 }
+// src/response/compression.ts
+var DEFAULT_COMPRESSION = {
+  enabled: true,
+  level: 6,
+  threshold: 1024
+};
+function isCompressible(contentType) {
+  if (!contentType)
+    return false;
+  const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  if (type.startsWith("text/"))
+    return true;
+  return [
+    "application/json",
+    "application/ld+json",
+    "application/manifest+json",
+    "application/javascript",
+    "application/x-javascript",
+    "application/xml",
+    "application/xhtml+xml",
+    "application/rss+xml",
+    "application/atom+xml",
+    "application/graphql",
+    "application/x-ndjson",
+    "image/svg+xml"
+  ].includes(type);
+}
+function negotiateEncoding(header) {
+  if (!header)
+    return null;
+  const offers = new Map;
+  for (const part of header.split(",")) {
+    const [name = "", ...parameters] = part.trim().split(";");
+    const quality = parameters.map((parameter) => /^\s*q=([\d.]+)\s*$/i.exec(parameter)).find(Boolean);
+    offers.set(name.trim().toLowerCase(), quality ? Number(quality[1]) : 1);
+  }
+  const wanted = (name) => (offers.get(name) ?? offers.get("*") ?? 0) > 0;
+  if (wanted("gzip"))
+    return "gzip";
+  if (wanted("deflate"))
+    return "deflate";
+  return null;
+}
+function shouldCompress(response, encoding, threshold) {
+  if (!encoding)
+    return false;
+  if (response.status === 204 || response.status === 304 || response.status === 206)
+    return false;
+  if (response.headers.has("content-encoding"))
+    return false;
+  if (!isCompressible(response.headers.get("content-type")))
+    return false;
+  if (!response.body)
+    return false;
+  const length = Number(response.headers.get("content-length") ?? Number.NaN);
+  return Number.isFinite(length) ? length >= threshold : true;
+}
+async function compressResponse(response, request2, options = {}) {
+  const settings = { ...DEFAULT_COMPRESSION, ...options };
+  if (!settings.enabled)
+    return response;
+  const encoding = negotiateEncoding(request2.headers.get("accept-encoding"));
+  if (!shouldCompress(response, encoding, settings.threshold)) {
+    if (isCompressible(response.headers.get("content-type")) && !response.headers.has("content-encoding"))
+      appendVary(response.headers, "Accept-Encoding");
+    return response;
+  }
+  const headers = new Headers(response.headers);
+  headers.set("Content-Encoding", encoding);
+  appendVary(headers, "Accept-Encoding");
+  headers.delete("Content-Length");
+  const compressed = response.body.pipeThrough(new CompressionStream(encoding === "gzip" ? "gzip" : "deflate"));
+  return new Response(compressed, { status: response.status, statusText: response.statusText, headers });
+}
+function appendVary(headers, value) {
+  const existing = headers.get("vary");
+  if (!existing) {
+    headers.set("Vary", value);
+    return;
+  }
+  const parts = existing.split(",").map((part) => part.trim().toLowerCase());
+  if (parts.includes("*") || parts.includes(value.toLowerCase()))
+    return;
+  headers.set("Vary", `${existing}, ${value}`);
+}
 // src/response/response-factory.ts
 var response = {
   json: (data, options = {}) => {
@@ -9563,7 +9648,8 @@ function registerServerHandling(RouterClass) {
     handleRequest: {
       async value(req) {
         const self = this;
-        return runWithRequest(req, () => self.handleRequestImpl(req));
+        const response2 = await runWithRequest(req, () => self.handleRequestImpl(req));
+        return await compressResponse(response2, req, self.config?.compression ?? {});
       },
       writable: true,
       configurable: true
@@ -13664,6 +13750,7 @@ export {
   spyOnMiddleware,
   singleFileUpload,
   signRequest,
+  shouldCompress,
   setCurrentRequest,
   setContainer,
   session,
@@ -13695,6 +13782,7 @@ export {
   parseThrottleString,
   oauth2Auth,
   normalizePath,
+  negotiateEncoding,
   multipleFileUpload,
   modelMocks,
   mockMiddleware,
@@ -13706,6 +13794,7 @@ export {
   jsonBody,
   joinPaths,
   isRouteHandler,
+  isCompressible,
   isActionClass,
   inputValidation,
   injectQueryPreservationScript,
@@ -13763,6 +13852,7 @@ export {
   contentSecurityPolicy,
   constraintHelpers,
   config,
+  compressResponse,
   clearNamedRoutes,
   buildUrlWithPreservedParams,
   benchmarkTests,
@@ -13773,6 +13863,7 @@ export {
   authHelpers,
   auth,
   applyRequestEnhancements,
+  appendVary,
   apiKeyAuth,
   WebSocketTester,
   Validator,
@@ -13854,6 +13945,7 @@ export {
   DefaultServiceProviderManager,
   DatabaseSessionStore,
   DatabaseRules,
+  DEFAULT_COMPRESSION,
   DDoSProtection,
   Csrf,
   Cors,

package/dist/response/compression.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Compressing what goes back, which nothing was doing.
+ *
+ * Static files have been served gzipped for a long time; every response a
+ * *route* produced went out whole. A server-rendered page is the shape that
+ * costs: the landing page of the application this was found in is 253 KB of
+ * HTML and compresses to about a tenth of that, on every request, for every
+ * visitor - and the same is true of any JSON list long enough to matter.
+ *
+ * Three rules:
+ *
+ * - **Only when the client asked.** `Accept-Encoding` decides, and `Vary` says
+ *   so, because a cache that hands a gzipped body to a client that did not ask
+ *   is a cache that breaks that client.
+ * - **Only when it is worth it.** Below a kilobyte the header costs more than
+ *   the saving, and already-compressed bytes (an image, a woff2, a zip) get
+ *   bigger rather than smaller.
+ * - **Never by buffering.** The body is piped through a `CompressionStream`
+ *   rather than read into memory, so a response that streams keeps streaming:
+ *   the diff manifest that sends a hundred files as they parse still arrives a
+ *   file at a time, compressed. Buffering to compress would have turned this
+ *   product's progressive render into a wait, which is a worse trade than the
+ *   bytes are worth.
+ *
+ * A piped body has no length until it ends, so `Content-Length` comes off and
+ * the response goes out chunked. That is the ordinary shape for a compressed
+ * response and every client handles it; a browser showing a page as it arrives
+ * is not waiting for a number.
+ */
+/** zlib's own range, so a level Bun would reject is a type error rather than a throw. */
+export type CompressionLevel = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+export interface CompressionOptions {
+    /** Off turns the whole thing off, for a proxy that already compresses. */
+    enabled?: boolean;
+    /**
+     * Kept for callers that set it, and unused by the stream path.
+     *
+     * `CompressionStream` has no level knob - it is the platform's, at its own
+     * default - and piping is what keeps a streamed response streaming. A level
+     * would mean going back to buffering, which is the trade this deliberately
+     * does not make.
+     */
+    level?: CompressionLevel;
+    /** Bodies below this many bytes are sent as they are. */
+    threshold?: number;
+}
+export declare const DEFAULT_COMPRESSION: Required<CompressionOptions>;
+/**
+ * Content types worth compressing.
+ *
+ * A prefix list rather than a regex over everything: `image/svg+xml` is text
+ * and compresses well, `image/png` is already compressed and grows. When in
+ * doubt the answer is no, because sending something slightly larger is a
+ * wasted CPU cycle and a wasted byte, while failing to compress is only a
+ * missed saving.
+ */
+export declare function isCompressible(contentType: string | null): boolean;
+/**
+ * The encoding to use, from what the client offered.
+ *
+ * gzip before deflate, and `q=0` respected - a client that says
+ * `gzip;q=0` means it, and sending gzip anyway is how you get an unreadable
+ * page in the one browser that asked.
+ *
+ * Brotli is not offered even though Bun can produce it: `Bun.gzipSync` is
+ * synchronous and brotli is not, and a compression step that awaits inside the
+ * response path is a different change from this one.
+ */
+export declare function negotiateEncoding(header: string | null): 'gzip' | 'deflate' | null;
+/**
+ * Whether this response should be compressed at all.
+ *
+ * `Content-Length` is a *hint here rather than a requirement*: Bun does not put
+ * one on a `Response` built from a string, so treating its absence as "this is
+ * a stream, leave it alone" left every server-rendered page uncompressed - the
+ * exact case this exists for. When there is a length, it decides against
+ * bodies too small to be worth it; when there is not, the body is piped and
+ * the threshold cannot apply.
+ */
+export declare function shouldCompress(response: Response, encoding: string | null, threshold: number): boolean;
+/**
+ * The response, compressed when that is the right thing to do.
+ *
+ * Returns the response it was given when it is not, so a caller can apply this
+ * unconditionally at the end of the pipeline.
+ */
+export declare function compressResponse(response: Response, request: Request, options?: CompressionOptions): Promise<Response>;
+/** Add to `Vary` without dropping what is already there. */
+export declare function appendVary(headers: Headers, value: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/bun-router",
   "type": "module",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "A fast, type-safe router for Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",