@remix-run/response 0.0.0 → 0.2.0

package/README.md

@@ -10,6 +10,7 @@ Basically, these are all the static response helpers we wish existed on the `Res
 - [**File Responses:**](#file-responses) Full HTTP semantics including ETags, Last-Modified, conditional requests, and Range support
 - [**HTML Responses:**](#html-responses) Automatic DOCTYPE prepending and proper Content-Type headers
 - [**Redirect Responses:**](#redirect-responses) Simple redirect creation with customizable status codes
+- [**Compress Responses:**](#compress-responses) Streaming compression based on Accept-Encoding header
 
 ## Installation
 
@@ -25,6 +26,7 @@ This package provides no default export. Instead, import the specific helper you
 import { createFileResponse } from '@remix-run/response/file'
 import { createHtmlResponse } from '@remix-run/response/html'
 import { createRedirectResponse } from '@remix-run/response/redirect'
+import { compressResponse } from '@remix-run/response/compress'
 ```
 
 ### File Responses
@@ -163,12 +165,74 @@ let response = createRedirectResponse('/dashboard', {
 })
 ```
 
+### Compress Responses
+
+The `compressResponse` helper compresses a `Response` based on the client's `Accept-Encoding` header:
+
+```ts
+import { compressResponse } from '@remix-run/response/compress'
+
+let response = new Response(JSON.stringify(data), {
+  headers: { 'Content-Type': 'application/json' },
+})
+let compressed = await compressResponse(response, request)
+```
+
+Compression is automatically skipped for:
+
+- Responses with no `Accept-Encoding` header
+- Responses that are already compressed (existing `Content-Encoding`)
+- Responses with `Cache-Control: no-transform`
+- Responses with `Content-Length` below threshold (default: 1024 bytes)
+- Responses with range support (`Accept-Ranges: bytes`)
+- 206 Partial Content responses
+- HEAD requests (only headers are modified)
+
+#### Options
+
+The `compressResponse` helper accepts options to customize compression behavior:
+
+```ts
+await compressResponse(response, request, {
+  // Minimum size in bytes to compress (only enforced if Content-Length is present).
+  // Default: 1024
+  threshold: 1024,
+
+  // Which encodings the server supports for negotiation.
+  // Defaults to ['br', 'gzip', 'deflate']
+  encodings: ['br', 'gzip', 'deflate'],
+
+  // node:zlib options for gzip/deflate compression.
+  // For SSE responses (text/event-stream), flush: Z_SYNC_FLUSH
+  // is automatically applied unless you explicitly set a flush value.
+  // See: https://nodejs.org/api/zlib.html#class-options
+  zlib: {
+    level: 6,
+  },
+
+  // node:zlib options for Brotli compression.
+  // For SSE responses (text/event-stream), flush: BROTLI_OPERATION_FLUSH
+  // is automatically applied unless you explicitly set a flush value.
+  // See: https://nodejs.org/api/zlib.html#class-brotlioptions
+  brotli: {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+    },
+  },
+})
+```
+
+#### Range Requests and Compression
+
+Range requests and compression are mutually exclusive. When `Accept-Ranges: bytes` is present in the response headers, `compressResponse` will not compress the response. This is why the `createFileResponse` helper enables ranges only for non-compressible MIME types by default - to allow text-based assets to be compressed while still supporting resumable downloads for media files.
+
 ## Related Packages
 
 - [`@remix-run/headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Type-safe HTTP header manipulation
 - [`@remix-run/html-template`](https://github.com/remix-run/remix/tree/main/packages/html-template) - Safe HTML templating with automatic escaping
 - [`@remix-run/fs`](https://github.com/remix-run/remix/tree/main/packages/fs) - File system utilities including `openFile`
 - [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Build HTTP routers using the web fetch API
+- [`@remix-run/mime`](https://github.com/remix-run/remix/tree/main/packages/mime) - MIME type utilities
 
 ## License
 

package/dist/compress.d.ts

@@ -0,0 +1,2 @@
+export { compressResponse, type CompressResponseOptions, type Encoding } from './lib/compress.ts';
+//# sourceMappingURL=compress.d.ts.map

package/dist/compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/compress.js

@@ -0,0 +1 @@
+export { compressResponse } from "./lib/compress.js";

package/dist/lib/compress.d.ts

@@ -0,0 +1,68 @@
+import { type BrotliCompress, type Gzip, type Deflate } from 'node:zlib';
+import type { BrotliOptions, ZlibOptions } from 'node:zlib';
+export type Encoding = 'br' | 'gzip' | 'deflate';
+export interface CompressResponseOptions {
+    /**
+     * Minimum size in bytes to compress (only enforced if Content-Length is present).
+     * If Content-Length is absent, compression is applied regardless of this threshold.
+     *
+     * Default: 1024
+     */
+    threshold?: number;
+    /**
+     * Which encodings the server supports for negotiation in order of preference.
+     * Supported encodings: 'br', 'gzip', 'deflate'.
+     * Default: ['br', 'gzip', 'deflate']
+     */
+    encodings?: Encoding[];
+    /**
+     * node:zlib options for gzip/deflate compression.
+     *
+     * For SSE responses (text/event-stream), `flush: Z_SYNC_FLUSH` is automatically
+     * applied unless you explicitly set a flush value.
+     *
+     * See: https://nodejs.org/api/zlib.html#class-options
+     */
+    zlib?: ZlibOptions;
+    /**
+     * node:zlib options for Brotli compression.
+     *
+     * For SSE responses (text/event-stream), `flush: BROTLI_OPERATION_FLUSH` is
+     * automatically applied unless you explicitly set a flush value.
+     *
+     * See: https://nodejs.org/api/zlib.html#class-brotlioptions
+     */
+    brotli?: BrotliOptions;
+}
+/**
+ * Compresses a Response based on the client's Accept-Encoding header.
+ *
+ * Compression is skipped for:
+ * - Responses with no Accept-Encoding header (RFC 7231)
+ * - Empty responses
+ * - Already compressed responses
+ * - Responses with Content-Length below threshold (default: 1024 bytes)
+ * - Responses with Cache-Control: no-transform
+ * - Responses advertising range support (Accept-Ranges: bytes)
+ * - Partial content responses (206 status)
+ *
+ * When compressing, this function:
+ * - Sets Content-Encoding header
+ * - Removes Content-Length header
+ * - Sets Accept-Ranges to 'none'
+ * - Adds 'Accept-Encoding' to Vary header
+ * - Converts strong ETags to weak ETags (per RFC 7232)
+ *
+ * @param response The response to compress
+ * @param request The request (needed to check Accept-Encoding header)
+ * @param options Optional compression settings
+ * @returns A compressed Response or the original if no compression is suitable
+ */
+export declare function compressResponse(response: Response, request: Request, options?: CompressResponseOptions): Promise<Response>;
+/**
+ * Compresses a response stream that bridges node:zlib to Web Streams.
+ * Reads from the input stream, compresses chunks through the compressor,
+ * and returns a new ReadableStream with the compressed data.
+ */
+export declare function compressStream(input: ReadableStream<Uint8Array>, compressor: Gzip | Deflate | BrotliCompress): ReadableStream<Uint8Array>;
+//# sourceMappingURL=compress.d.ts.map

package/dist/lib/compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/lib/compress.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,OAAO,EACb,MAAM,WAAW,CAAA;AAClB,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAI3D,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAA;AAGhD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;IAEtB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAuDnB;AA8ED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,EACjC,UAAU,EAAE,IAAI,GAAG,OAAO,GAAG,cAAc,GAC1C,cAAc,CAAC,UAAU,CAAC,CA2F5B"}

package/dist/lib/compress.js

@@ -0,0 +1,226 @@
+import { constants, createBrotliCompress, createDeflate, createGzip, } from 'node:zlib';
+import { AcceptEncoding, SuperHeaders } from '@remix-run/headers';
+const defaultEncodings = ['br', 'gzip', 'deflate'];
+/**
+ * Compresses a Response based on the client's Accept-Encoding header.
+ *
+ * Compression is skipped for:
+ * - Responses with no Accept-Encoding header (RFC 7231)
+ * - Empty responses
+ * - Already compressed responses
+ * - Responses with Content-Length below threshold (default: 1024 bytes)
+ * - Responses with Cache-Control: no-transform
+ * - Responses advertising range support (Accept-Ranges: bytes)
+ * - Partial content responses (206 status)
+ *
+ * When compressing, this function:
+ * - Sets Content-Encoding header
+ * - Removes Content-Length header
+ * - Sets Accept-Ranges to 'none'
+ * - Adds 'Accept-Encoding' to Vary header
+ * - Converts strong ETags to weak ETags (per RFC 7232)
+ *
+ * @param response The response to compress
+ * @param request The request (needed to check Accept-Encoding header)
+ * @param options Optional compression settings
+ * @returns A compressed Response or the original if no compression is suitable
+ */
+export async function compressResponse(response, request, options) {
+    let compressOptions = options ?? {};
+    let supportedEncodings = compressOptions.encodings ?? defaultEncodings;
+    let threshold = compressOptions.threshold ?? 1024;
+    let acceptEncodingHeader = request.headers.get('Accept-Encoding');
+    let responseHeaders = new SuperHeaders(response.headers);
+    if (!acceptEncodingHeader ||
+        supportedEncodings.length === 0 ||
+        // Empty response
+        (request.method !== 'HEAD' && !response.body) ||
+        // Already compressed
+        responseHeaders.contentEncoding != null ||
+        // Content-Length below threshold
+        (responseHeaders.contentLength != null && responseHeaders.contentLength < threshold) ||
+        // Cache-Control: no-transform
+        responseHeaders.cacheControl.noTransform ||
+        // Response advertising range support
+        responseHeaders.acceptRanges === 'bytes' ||
+        // Partial content responses
+        response.status === 206) {
+        return response;
+    }
+    let acceptEncoding = new AcceptEncoding(acceptEncodingHeader);
+    let selectedEncoding = negotiateEncoding(acceptEncoding, supportedEncodings);
+    if (selectedEncoding === null) {
+        // Client has explicitly rejected all supported encodings, including 'identity'
+        return new Response(`Only ${[supportedEncodings, 'identity'].map((encoding) => `'${encoding}'`).join(', ')} encodings are supported`, {
+            status: 406,
+            statusText: 'Not Acceptable',
+        });
+    }
+    if (selectedEncoding === 'identity') {
+        return response;
+    }
+    // For HEAD requests, set compression headers without actually compressing
+    if (request.method === 'HEAD') {
+        setCompressionHeaders(responseHeaders, selectedEncoding);
+        return new Response(null, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+        });
+    }
+    return applyCompression(response, responseHeaders, selectedEncoding, compressOptions);
+}
+function negotiateEncoding(acceptEncoding, supportedEncodings) {
+    if (acceptEncoding.encodings.length === 0) {
+        return 'identity';
+    }
+    let preferred = acceptEncoding.getPreferred(supportedEncodings);
+    if (!preferred) {
+        // Clients can explicitly reject 'identity' by setting its weight to 0,
+        // otherwise it is considered an acceptable fallback.
+        return acceptEncoding.getWeight('identity') === 0 ? null : 'identity';
+    }
+    return preferred;
+}
+function setCompressionHeaders(headers, encoding) {
+    headers.contentEncoding = encoding;
+    headers.acceptRanges = 'none';
+    headers.contentLength = null;
+    headers.vary.add('Accept-Encoding');
+    // Convert strong ETags to weak since compressed representation is byte-different
+    if (headers.etag && !headers.etag.startsWith('W/')) {
+        headers.etag = `W/${headers.etag}`;
+    }
+}
+const zlibFlushOptions = {
+    flush: constants.Z_SYNC_FLUSH,
+};
+const brotliFlushOptions = {
+    flush: constants.BROTLI_OPERATION_FLUSH,
+};
+function applyCompression(response, responseHeaders, encoding, options) {
+    if (!response.body) {
+        return response;
+    }
+    // Detect SSE for automatic flush configuration
+    let contentType = response.headers.get('Content-Type');
+    let mediaType = contentType?.split(';')[0].trim();
+    let isSSE = mediaType === 'text/event-stream';
+    let compressor = createCompressor(encoding, {
+        ...options,
+        // Apply SSE flush defaults if not explicitly set
+        brotli: {
+            ...options.brotli,
+            ...(isSSE && options.brotli?.flush === undefined ? brotliFlushOptions : null),
+        },
+        zlib: {
+            ...options.zlib,
+            ...(isSSE && options.zlib?.flush === undefined ? zlibFlushOptions : null),
+        },
+    });
+    setCompressionHeaders(responseHeaders, encoding);
+    return new Response(compressStream(response.body, compressor), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+    });
+}
+/**
+ * Compresses a response stream that bridges node:zlib to Web Streams.
+ * Reads from the input stream, compresses chunks through the compressor,
+ * and returns a new ReadableStream with the compressed data.
+ */
+export function compressStream(input, compressor) {
+    let reader = null;
+    let cancelled = false;
+    let errored = false;
+    return new ReadableStream({
+        async start(controller) {
+            reader = input.getReader();
+            compressor.on('data', (chunk) => {
+                if (!cancelled && !errored) {
+                    controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+                }
+            });
+            compressor.on('end', () => {
+                if (!cancelled && !errored) {
+                    controller.close();
+                }
+            });
+            compressor.on('error', (error) => {
+                // Ignore duplicate error events
+                if (errored) {
+                    return;
+                }
+                errored = true;
+                if (!cancelled) {
+                    controller.error(error);
+                }
+            });
+            try {
+                while (true) {
+                    if (cancelled || errored) {
+                        break;
+                    }
+                    let { done, value } = await reader.read();
+                    if (cancelled || errored) {
+                        break;
+                    }
+                    if (done) {
+                        compressor.end();
+                        break;
+                    }
+                    if (!value) {
+                        continue;
+                    }
+                    await new Promise((resolve, reject) => {
+                        let resolvedImmediately = false;
+                        let canContinue = compressor.write(Buffer.from(value), (error) => {
+                            if (resolvedImmediately) {
+                                return;
+                            }
+                            if (error) {
+                                reject(error);
+                            }
+                            else {
+                                resolve();
+                            }
+                        });
+                        if (canContinue) {
+                            resolvedImmediately = true;
+                            resolve();
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                errored = true;
+                compressor.destroy(error);
+                if (!cancelled) {
+                    controller.error(error);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+        async cancel(reason) {
+            cancelled = true;
+            // Destroy compressor first to unblock any pending write operations
+            compressor.destroy();
+            await reader?.cancel(reason);
+        },
+    });
+}
+function createCompressor(encoding, options) {
+    switch (encoding) {
+        case 'br':
+            return createBrotliCompress(options.brotli);
+        case 'gzip':
+            return createGzip(options.zlib);
+        case 'deflate':
+            return createDeflate(options.zlib);
+        default:
+            throw new Error(`Unsupported encoding: ${encoding}`);
+    }
+}

package/dist/lib/file.d.ts

@@ -2,7 +2,7 @@
  * Custom function for computing file digests.
  *
  * @param file The file to hash
- * @returns The computed digest as a string
+ * @return The computed digest as a string
  *
  * @example
  * async (file) => {
@@ -11,6 +11,9 @@
  * }
  */
 export type FileDigestFunction = (file: File) => Promise<string>;
+/**
+ * Options for creating a file response.
+ */
 export interface FileResponseOptions {
     /**
      * Cache-Control header value. If not provided, no Cache-Control header will be set.
@@ -56,7 +59,13 @@ export interface FileResponseOptions {
      * When enabled, includes `Accept-Ranges` header and handles `Range` requests
      * with 206 Partial Content responses.
      *
-     * @default true
+     * Defaults to enabling ranges only for non-compressible MIME types,
+     * as defined by `isCompressibleMimeType()` from `@remix-run/mime`.
+     *
+     * Note: Range requests and compression are mutually exclusive. When
+     * `Accept-Ranges: bytes` is present in the response headers, the compression
+     * middleware will not compress the response. This is why the default behavior
+     * enables ranges only for non-compressible types.
      */
     acceptRanges?: boolean;
 }
@@ -66,8 +75,8 @@ export interface FileResponseOptions {
  *
  * @param file The file to send
  * @param request The request object
- * @param options (optional) configuration options
- * @returns A `Response` object containing the file
+ * @param options Configuration options
+ * @return A `Response` object containing the file
  *
  * @example
  * import { createFileResponse } from '@remix-run/response/file'

package/dist/lib/file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/lib/file.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAEhE,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;IAChC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAAA;IACjD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CA0KnB"}
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/lib/file.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAEhE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;IAChC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAAA;IACjD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CA+KnB"}

package/dist/lib/file.js

@@ -1,12 +1,13 @@
 import SuperHeaders from '@remix-run/headers';
+import { isCompressibleMimeType } from '@remix-run/mime';
 /**
  * Creates a file [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
  * with full HTTP semantics including ETags, Last-Modified, conditional requests, and Range support.
  *
  * @param file The file to send
  * @param request The request object
- * @param options (optional) configuration options
- * @returns A `Response` object containing the file
+ * @param options Configuration options
+ * @return A `Response` object containing the file
  *
  * @example
  * import { createFileResponse } from '@remix-run/response/file'
@@ -16,7 +17,7 @@ import SuperHeaders from '@remix-run/headers';
  * })
  */
 export async function createFileResponse(file, request, options = {}) {
-    let { cacheControl, etag: etagStrategy = 'weak', digest: digestOption = 'SHA-256', lastModified: lastModifiedEnabled = true, acceptRanges: acceptRangesEnabled = true, } = options;
+    let { cacheControl, etag: etagStrategy = 'weak', digest: digestOption = 'SHA-256', lastModified: lastModifiedEnabled = true, acceptRanges: acceptRangesOption, } = options;
     let headers = new SuperHeaders(request.headers);
     let contentType = file.type;
     let contentLength = file.size;
@@ -32,6 +33,9 @@ export async function createFileResponse(file, request, options = {}) {
     if (lastModifiedEnabled) {
         lastModified = file.lastModified;
     }
+    // Determine if we should accept ranges
+    // Default: enable ranges only for non-compressible MIME types
+    let acceptRangesEnabled = acceptRangesOption !== undefined ? acceptRangesOption : !isCompressibleMimeType(contentType);
     let acceptRanges;
     if (acceptRangesEnabled) {
         acceptRanges = 'bytes';

package/dist/lib/html.d.ts

@@ -4,9 +4,9 @@ type HtmlBody = string | SafeHtml | Blob | BufferSource | ReadableStream<Uint8Ar
  * Creates an HTML [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
  * that ensures the response has a valid DOCTYPE and appropriate `Content-Type` header.
  *
- * @param body The body of the response.
- * @param init (optional) The `ResponseInit` object for the response.
- * @returns A `Response` object with a HTML body and the appropriate `Content-Type` header.
+ * @param body The body of the response
+ * @param init The `ResponseInit` object for the response
+ * @return A `Response` object with a HTML body and the appropriate `Content-Type` header
  */
 export declare function createHtmlResponse(body: HtmlBody, init?: ResponseInit): Response;
 export {};

package/dist/lib/html.js

@@ -4,9 +4,9 @@ const DOCTYPE = '<!DOCTYPE html>';
  * Creates an HTML [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
  * that ensures the response has a valid DOCTYPE and appropriate `Content-Type` header.
  *
- * @param body The body of the response.
- * @param init (optional) The `ResponseInit` object for the response.
- * @returns A `Response` object with a HTML body and the appropriate `Content-Type` header.
+ * @param body The body of the response
+ * @param init The `ResponseInit` object for the response
+ * @return A `Response` object with a HTML body and the appropriate `Content-Type` header
  */
 export function createHtmlResponse(body, init) {
     let payload = ensureDoctype(body);

package/dist/lib/redirect.d.ts

@@ -2,7 +2,7 @@
  * Creates a redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
  *
  * @param location The location to redirect to
- * @param init (optional) The `ResponseInit` object for the response, or a status code
+ * @param init The `ResponseInit` object for the response, or a status code
  * @returns A `Response` object with a redirect header
  */
 export declare function createRedirectResponse(location: string | URL, init?: ResponseInit | number): Response;

package/dist/lib/redirect.js

@@ -2,7 +2,7 @@
  * Creates a redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
  *
  * @param location The location to redirect to
- * @param init (optional) The `ResponseInit` object for the response, or a status code
+ * @param init The `ResponseInit` object for the response, or a status code
  * @returns A `Response` object with a redirect header
  */
 export function createRedirectResponse(location, init) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remix-run/response",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Response helpers for the web Fetch API",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -19,6 +19,10 @@
   ],
   "type": "module",
   "exports": {
+    "./compress": {
+      "types": "./dist/compress.d.ts",
+      "default": "./dist/compress.js"
+    },
     "./file": {
       "types": "./dist/file.d.ts",
       "default": "./dist/file.js"
@@ -35,11 +39,13 @@
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@remix-run/mime": "0.1.0"
   },
   "peerDependencies": {
-    "@remix-run/headers": "^0.17.1",
-    "@remix-run/html-template": "^0.3.0"
+    "@remix-run/headers": "^0.18.0",
+    "@remix-run/html-template": "^0.3.0",
+    "@remix-run/mime": "^0.1.0"
   },
   "keywords": [
     "fetch",

package/src/compress.ts

@@ -0,0 +1 @@
+export { compressResponse, type CompressResponseOptions, type Encoding } from './lib/compress.ts'

package/src/lib/compress.ts

@@ -0,0 +1,330 @@
+import {
+  constants,
+  createBrotliCompress,
+  createDeflate,
+  createGzip,
+  type BrotliCompress,
+  type Gzip,
+  type Deflate,
+} from 'node:zlib'
+import type { BrotliOptions, ZlibOptions } from 'node:zlib'
+
+import { AcceptEncoding, SuperHeaders } from '@remix-run/headers'
+
+export type Encoding = 'br' | 'gzip' | 'deflate'
+const defaultEncodings: Encoding[] = ['br', 'gzip', 'deflate']
+
+export interface CompressResponseOptions {
+  /**
+   * Minimum size in bytes to compress (only enforced if Content-Length is present).
+   * If Content-Length is absent, compression is applied regardless of this threshold.
+   *
+   * Default: 1024
+   */
+  threshold?: number
+
+  /**
+   * Which encodings the server supports for negotiation in order of preference.
+   * Supported encodings: 'br', 'gzip', 'deflate'.
+   * Default: ['br', 'gzip', 'deflate']
+   */
+  encodings?: Encoding[]
+
+  /**
+   * node:zlib options for gzip/deflate compression.
+   *
+   * For SSE responses (text/event-stream), `flush: Z_SYNC_FLUSH` is automatically
+   * applied unless you explicitly set a flush value.
+   *
+   * See: https://nodejs.org/api/zlib.html#class-options
+   */
+  zlib?: ZlibOptions
+
+  /**
+   * node:zlib options for Brotli compression.
+   *
+   * For SSE responses (text/event-stream), `flush: BROTLI_OPERATION_FLUSH` is
+   * automatically applied unless you explicitly set a flush value.
+   *
+   * See: https://nodejs.org/api/zlib.html#class-brotlioptions
+   */
+  brotli?: BrotliOptions
+}
+
+/**
+ * Compresses a Response based on the client's Accept-Encoding header.
+ *
+ * Compression is skipped for:
+ * - Responses with no Accept-Encoding header (RFC 7231)
+ * - Empty responses
+ * - Already compressed responses
+ * - Responses with Content-Length below threshold (default: 1024 bytes)
+ * - Responses with Cache-Control: no-transform
+ * - Responses advertising range support (Accept-Ranges: bytes)
+ * - Partial content responses (206 status)
+ *
+ * When compressing, this function:
+ * - Sets Content-Encoding header
+ * - Removes Content-Length header
+ * - Sets Accept-Ranges to 'none'
+ * - Adds 'Accept-Encoding' to Vary header
+ * - Converts strong ETags to weak ETags (per RFC 7232)
+ *
+ * @param response The response to compress
+ * @param request The request (needed to check Accept-Encoding header)
+ * @param options Optional compression settings
+ * @returns A compressed Response or the original if no compression is suitable
+ */
+export async function compressResponse(
+  response: Response,
+  request: Request,
+  options?: CompressResponseOptions,
+): Promise<Response> {
+  let compressOptions = options ?? {}
+  let supportedEncodings = compressOptions.encodings ?? defaultEncodings
+  let threshold = compressOptions.threshold ?? 1024
+  let acceptEncodingHeader = request.headers.get('Accept-Encoding')
+  let responseHeaders = new SuperHeaders(response.headers)
+
+  if (
+    !acceptEncodingHeader ||
+    supportedEncodings.length === 0 ||
+    // Empty response
+    (request.method !== 'HEAD' && !response.body) ||
+    // Already compressed
+    responseHeaders.contentEncoding != null ||
+    // Content-Length below threshold
+    (responseHeaders.contentLength != null && responseHeaders.contentLength < threshold) ||
+    // Cache-Control: no-transform
+    responseHeaders.cacheControl.noTransform ||
+    // Response advertising range support
+    responseHeaders.acceptRanges === 'bytes' ||
+    // Partial content responses
+    response.status === 206
+  ) {
+    return response
+  }
+
+  let acceptEncoding = new AcceptEncoding(acceptEncodingHeader)
+  let selectedEncoding = negotiateEncoding(acceptEncoding, supportedEncodings)
+  if (selectedEncoding === null) {
+    // Client has explicitly rejected all supported encodings, including 'identity'
+    return new Response(
+      `Only ${[supportedEncodings, 'identity'].map((encoding) => `'${encoding}'`).join(', ')} encodings are supported`,
+      {
+        status: 406,
+        statusText: 'Not Acceptable',
+      },
+    )
+  }
+
+  if (selectedEncoding === 'identity') {
+    return response
+  }
+
+  // For HEAD requests, set compression headers without actually compressing
+  if (request.method === 'HEAD') {
+    setCompressionHeaders(responseHeaders, selectedEncoding)
+
+    return new Response(null, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+    })
+  }
+
+  return applyCompression(response, responseHeaders, selectedEncoding, compressOptions)
+}
+
+function negotiateEncoding(
+  acceptEncoding: AcceptEncoding,
+  supportedEncodings: readonly Encoding[],
+): Encoding | 'identity' | null {
+  if (acceptEncoding.encodings.length === 0) {
+    return 'identity'
+  }
+
+  let preferred = acceptEncoding.getPreferred(supportedEncodings)
+
+  if (!preferred) {
+    // Clients can explicitly reject 'identity' by setting its weight to 0,
+    // otherwise it is considered an acceptable fallback.
+    return acceptEncoding.getWeight('identity') === 0 ? null : 'identity'
+  }
+
+  return preferred
+}
+
+function setCompressionHeaders(headers: SuperHeaders, encoding: string): void {
+  headers.contentEncoding = encoding
+  headers.acceptRanges = 'none'
+  headers.contentLength = null
+  headers.vary.add('Accept-Encoding')
+
+  // Convert strong ETags to weak since compressed representation is byte-different
+  if (headers.etag && !headers.etag.startsWith('W/')) {
+    headers.etag = `W/${headers.etag}`
+  }
+}
+
+const zlibFlushOptions = {
+  flush: constants.Z_SYNC_FLUSH,
+}
+
+const brotliFlushOptions = {
+  flush: constants.BROTLI_OPERATION_FLUSH,
+}
+
+function applyCompression(
+  response: Response,
+  responseHeaders: SuperHeaders,
+  encoding: Encoding,
+  options: CompressResponseOptions,
+): Response {
+  if (!response.body) {
+    return response
+  }
+
+  // Detect SSE for automatic flush configuration
+  let contentType = response.headers.get('Content-Type')
+  let mediaType = contentType?.split(';')[0].trim()
+  let isSSE = mediaType === 'text/event-stream'
+
+  let compressor = createCompressor(encoding, {
+    ...options,
+    // Apply SSE flush defaults if not explicitly set
+    brotli: {
+      ...options.brotli,
+      ...(isSSE && options.brotli?.flush === undefined ? brotliFlushOptions : null),
+    },
+    zlib: {
+      ...options.zlib,
+      ...(isSSE && options.zlib?.flush === undefined ? zlibFlushOptions : null),
+    },
+  })
+
+  setCompressionHeaders(responseHeaders, encoding)
+
+  return new Response(compressStream(response.body, compressor), {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders,
+  })
+}
+
+/**
+ * Compresses a response stream that bridges node:zlib to Web Streams.
+ * Reads from the input stream, compresses chunks through the compressor,
+ * and returns a new ReadableStream with the compressed data.
+ */
+export function compressStream(
+  input: ReadableStream<Uint8Array>,
+  compressor: Gzip | Deflate | BrotliCompress,
+): ReadableStream<Uint8Array> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
+  let cancelled = false
+  let errored = false
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      reader = input.getReader()
+
+      compressor.on('data', (chunk: Buffer) => {
+        if (!cancelled && !errored) {
+          controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength))
+        }
+      })
+
+      compressor.on('end', () => {
+        if (!cancelled && !errored) {
+          controller.close()
+        }
+      })
+
+      compressor.on('error', (error) => {
+        // Ignore duplicate error events
+        if (errored) {
+          return
+        }
+        errored = true
+        if (!cancelled) {
+          controller.error(error)
+        }
+      })
+
+      try {
+        while (true) {
+          if (cancelled || errored) {
+            break
+          }
+
+          let { done, value } = await reader.read()
+
+          if (cancelled || errored) {
+            break
+          }
+
+          if (done) {
+            compressor.end()
+            break
+          }
+
+          if (!value) {
+            continue
+          }
+
+          await new Promise<void>((resolve, reject) => {
+            let resolvedImmediately = false
+
+            let canContinue = compressor.write(Buffer.from(value), (error) => {
+              if (resolvedImmediately) {
+                return
+              }
+              if (error) {
+                reject(error)
+              } else {
+                resolve()
+              }
+            })
+
+            if (canContinue) {
+              resolvedImmediately = true
+              resolve()
+            }
+          })
+        }
+      } catch (error) {
+        errored = true
+        compressor.destroy(error as Error)
+        if (!cancelled) {
+          controller.error(error)
+        }
+      } finally {
+        reader.releaseLock()
+      }
+    },
+
+    async cancel(reason) {
+      cancelled = true
+      // Destroy compressor first to unblock any pending write operations
+      compressor.destroy()
+      await reader?.cancel(reason)
+    },
+  })
+}
+
+function createCompressor(
+  encoding: Encoding,
+  options: CompressResponseOptions,
+): Gzip | Deflate | BrotliCompress {
+  switch (encoding) {
+    case 'br':
+      return createBrotliCompress(options.brotli)
+    case 'gzip':
+      return createGzip(options.zlib)
+    case 'deflate':
+      return createDeflate(options.zlib)
+    default:
+      throw new Error(`Unsupported encoding: ${encoding}`)
+  }
+}

package/src/lib/file.ts

@@ -1,10 +1,11 @@
 import SuperHeaders from '@remix-run/headers'
+import { isCompressibleMimeType } from '@remix-run/mime'
 
 /**
  * Custom function for computing file digests.
  *
  * @param file The file to hash
- * @returns The computed digest as a string
+ * @return The computed digest as a string
  *
  * @example
  * async (file) => {
@@ -14,6 +15,9 @@ import SuperHeaders from '@remix-run/headers'
  */
 export type FileDigestFunction = (file: File) => Promise<string>
 
+/**
+ * Options for creating a file response.
+ */
 export interface FileResponseOptions {
   /**
    * Cache-Control header value. If not provided, no Cache-Control header will be set.
@@ -59,7 +63,13 @@ export interface FileResponseOptions {
    * When enabled, includes `Accept-Ranges` header and handles `Range` requests
    * with 206 Partial Content responses.
    *
-   * @default true
+   * Defaults to enabling ranges only for non-compressible MIME types,
+   * as defined by `isCompressibleMimeType()` from `@remix-run/mime`.
+   *
+   * Note: Range requests and compression are mutually exclusive. When
+   * `Accept-Ranges: bytes` is present in the response headers, the compression
+   * middleware will not compress the response. This is why the default behavior
+   * enables ranges only for non-compressible types.
    */
   acceptRanges?: boolean
 }
@@ -70,8 +80,8 @@ export interface FileResponseOptions {
  *
  * @param file The file to send
  * @param request The request object
- * @param options (optional) configuration options
- * @returns A `Response` object containing the file
+ * @param options Configuration options
+ * @return A `Response` object containing the file
  *
  * @example
  * import { createFileResponse } from '@remix-run/response/file'
@@ -90,7 +100,7 @@ export async function createFileResponse(
     etag: etagStrategy = 'weak',
     digest: digestOption = 'SHA-256',
     lastModified: lastModifiedEnabled = true,
-    acceptRanges: acceptRangesEnabled = true,
+    acceptRanges: acceptRangesOption,
   } = options
 
   let headers = new SuperHeaders(request.headers)
@@ -111,6 +121,11 @@ export async function createFileResponse(
     lastModified = file.lastModified
   }
 
+  // Determine if we should accept ranges
+  // Default: enable ranges only for non-compressible MIME types
+  let acceptRangesEnabled =
+    acceptRangesOption !== undefined ? acceptRangesOption : !isCompressibleMimeType(contentType)
+
   let acceptRanges: 'bytes' | undefined
   if (acceptRangesEnabled) {
     acceptRanges = 'bytes'

package/src/lib/html.ts

@@ -8,9 +8,9 @@ type HtmlBody = string | SafeHtml | Blob | BufferSource | ReadableStream<Uint8Ar
  * Creates an HTML [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
  * that ensures the response has a valid DOCTYPE and appropriate `Content-Type` header.
  *
- * @param body The body of the response.
- * @param init (optional) The `ResponseInit` object for the response.
- * @returns A `Response` object with a HTML body and the appropriate `Content-Type` header.
+ * @param body The body of the response
+ * @param init The `ResponseInit` object for the response
+ * @return A `Response` object with a HTML body and the appropriate `Content-Type` header
  */
 export function createHtmlResponse(body: HtmlBody, init?: ResponseInit): Response {
   let payload: BodyInit = ensureDoctype(body)

package/src/lib/redirect.ts

@@ -2,7 +2,7 @@
  * Creates a redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
  *
  * @param location The location to redirect to
- * @param init (optional) The `ResponseInit` object for the response, or a status code
+ * @param init The `ResponseInit` object for the response, or a status code
  * @returns A `Response` object with a redirect header
  */
 export function createRedirectResponse(