@morojs/moro 1.8.15 → 1.8.17

package/dist/core/middleware/built-in/compression/core.d.ts

@@ -1,7 +1,8 @@
 import { HttpRequest, HttpResponse } from '../../../../types/http.js';
-import { type Encoding } from '../../../http/utils/compression.js';
-export interface CompressionOptions {
+import { type Encoding, type EncoderOptions } from '../../../http/utils/compression.js';
+export interface CompressionOptions extends EncoderOptions {
     threshold?: number;
+    /** 1-9: the gzip level, and the brotli quality it maps to (see `gzip` / `brotli` to pin either). */
     level?: number;
     encodings?: Encoding[];
     /**
@@ -17,6 +18,7 @@ export declare class CompressionCore {
     private level;
     private encodings;
     private maxInlineBytes;
+    private encoders;
     private filter?;
     constructor(options?: CompressionOptions);
     shouldCompress(req: HttpRequest, res: HttpResponse): boolean;

package/dist/core/middleware/built-in/compression/core.js

@@ -4,12 +4,18 @@ export class CompressionCore {
     level;
     encodings;
     maxInlineBytes;
+    encoders;
     filter;
     constructor(options = {}) {
         this.threshold = options.threshold || 1024; // 1KB default
         this.level = options.level || 6; // Default compression level
         this.encodings = options.encodings || DEFAULT_ENCODINGS;
         this.maxInlineBytes = options.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+        this.encoders = {
+            ...(options.gzip !== undefined ? { gzip: options.gzip } : {}),
+            ...(options.brotli !== undefined ? { brotli: options.brotli } : {}),
+            ...(options.reuseEncoders !== undefined ? { reuseEncoders: options.reuseEncoders } : {}),
+        };
         this.filter = options.filter;
     }
     shouldCompress(req, res) {
@@ -28,6 +34,7 @@ export class CompressionCore {
         const threshold = this.threshold;
         const encodings = this.encodings;
         const maxInline = this.maxInlineBytes;
+        const encoders = this.encoders;
         const filterOk = this.filter ? this.filter(req, res) : true;
         const compressResponse = (data, isJson, contentType) => {
             const content = isJson ? JSON.stringify(data) : data;
@@ -59,7 +66,7 @@ export class CompressionCore {
             if (maxInline > 0 && byteLength <= maxInline && !res.headersSent) {
                 let compressed;
                 try {
-                    compressed = compressBufferSync(buffer, encoding, level);
+                    compressed = compressBufferSync(buffer, encoding, level, encoders);
                 }
                 catch {
                     if (isJson) {
@@ -91,14 +98,17 @@ export class CompressionCore {
                 res.setHeader('Vary', vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding');
                 res.writeHead(res.statusCode || 200);
             }
-            compressBuffer(buffer, encoding, level)
+            compressBuffer(buffer, encoding, level, encoders)
                 .then(compressed => res.end(compressed))
                 .catch(() => res.end()); // headers already committed - can't fall back to raw
             return res;
         };
         res.json = function (data) {
+            // The same type res.json sends without the middleware: JSON is UTF-8 by
+            // definition (RFC 8259 §8.1), so a charset parameter only adds bytes to
+            // every reply.
             if (!this.getHeader('Content-Type')) {
-                this.setHeader('Content-Type', 'application/json; charset=utf-8');
+                this.setHeader('Content-Type', 'application/json');
             }
             compressResponse(data, true, 'application/json');
             return this;

package/dist/core/middleware/built-in/compression/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../../src/core/middleware/built-in/compression/core.ts"],"names":[],"mappings":"AASA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GAEzB,MAAM,oCAAoC,CAAC;AAe5C,MAAM,OAAO,eAAe;IAClB,SAAS,CAAS;IAClB,KAAK,CAAS;IACd,SAAS,CAAa;IACtB,cAAc,CAAS;IACvB,MAAM,CAAkE;IAEhF,YAAY,UAA8B,EAAE;QAC1C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,cAAc;QAC1D,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,4BAA4B;QAC7D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,iBAAiB,CAAC;QACxD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;QACzE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,cAAc,CAAC,GAAgB,EAAE,GAAiB;QAChD,sBAAsB;QACtB,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,gDAAgD;QAChD,MAAM,cAAc,GAAI,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAY,IAAI,EAAE,CAAC;QACxE,OAAO,iBAAiB,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;IACpE,CAAC;IAED,YAAY,CAAC,GAAgB,EAAE,GAAiB;QAC9C,MAAM,YAAY,GAAG,GAAG,CAAC,IAAI,CAAC;QAC9B,MAAM,cAAc,GAAI,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAY,IAAI,EAAE,CAAC;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE5D,MAAM,gBAAgB,GAAG,CAAC,IAAS,EAAE,MAAe,EAAE,WAAoB,EAAE,EAAE;YAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACrD,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACzC,CAAC,CAAC,OAAO,CAAC,MAAM;gBAChB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YACrC,MAAM,QAAQ,GACZ,WAAW;gBACX,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAE,GAAG,CAAC,SAAS,CAAC,cAAc,CAAwB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACtF,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAEhF,oEAAoE;YACpE,yEAAyE;YACzE,sEAAsE;YACtE,sEAAsE;YACtE,0DAA0D;YAC1D,IAAI,UAAU,GAAG,SAAS,IAAI,CAAC,QAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACrE,IAAI,MAAM,EAAE,CAAC;oBACX,IAAI,GAAG,CAAC,WAAW;wBAAE,OAAO;oBAC5B,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;oBAC5C,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;oBACjB,OAAO;gBACT,CAAC;gBACD,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAE/E,uEAAuE;YACvE,oEAAoE;YACpE,wEAAwE;YACxE,IAAI,SAAS,GAAG,CAAC,IAAI,UAAU,IAAI,SAAS,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACjE,IAAI,UAAkB,CAAC;gBACvB,IAAI,CAAC;oBACH,UAAU,GAAG,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAC3D,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,MAAM,EAAE,CAAC;wBACX,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;wBAC5C,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;wBACjB,OAAO;oBACT,CAAC;oBACD,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACtC,CAAC;gBACD,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;gBAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAwB,CAAC,CAAC,CAAC,SAAS,CAAC;gBACvF,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;gBAC7E,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;gBACnD,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBACpB,OAAO,GAAG,CAAC;YACb,CAAC;YAED,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,wEAAwE;YACxE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,oEAAoE;gBACpE,iEAAiE;gBACjE,IAAI,OAAQ,GAAW,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;oBACnD,GAAW,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;gBAC9C,CAAC;gBACD,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;gBAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAwB,CAAC,CAAC,CAAC,SAAS,CAAC;gBACvF,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;gBAC5E,GAAW,CAAC,SAAS,CAAE,GAAW,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;YACzD,CAAC;YAED,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;iBACpC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;iBACvC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,qDAAqD;YAEhF,OAAO,GAAG,CAAC;QACb,CAAC,CAAC;QAEF,GAAG,CAAC,IAAI,GAAG,UAAU,IAAS;YAC5B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,iCAAiC,CAAC,CAAC;YACpE,CAAC;YACD,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QAEF,GAAG,CAAC,IAAI,GAAG,UAAU,IAAS;YAC5B,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;IACJ,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF","sourcesContent":["// Compression Core Logic\n//\n// The global compression middleware wraps res.json/res.send uniformly across\n// EVERY runtime (Node, uWS, HTTP/2, engine), so it is the single source of\n// response compression parity. It delegates encoding choice and content-type\n// filtering to the shared utility (utils/compression) so brotli, q-value\n// negotiation, and the compressible-type allowlist behave identically here and\n// in the per-server fallback paths.\nimport { HttpRequest, HttpResponse } from '../../../../types/http.js';\nimport {\n  compressBuffer,\n  compressBufferSync,\n  negotiateEncoding,\n  isCompressible,\n  DEFAULT_ENCODINGS,\n  DEFAULT_MAX_INLINE_BYTES,\n  type Encoding,\n} from '../../../http/utils/compression.js';\n\nexport interface CompressionOptions {\n  threshold?: number;\n  level?: number;\n  encodings?: Encoding[];\n  /**\n   * Bodies at or below this size are compressed on the calling thread and\n   * sent with a Content-Length; larger ones go to the threadpool and stream\n   * chunked. 0 sends every body through the pool. Default 16384.\n   */\n  maxInlineBytes?: number;\n  filter?: (req: HttpRequest, res: HttpResponse) => boolean;\n}\n\nexport class CompressionCore {\n  private threshold: number;\n  private level: number;\n  private encodings: Encoding[];\n  private maxInlineBytes: number;\n  private filter?: ((req: HttpRequest, res: HttpResponse) => boolean) | undefined;\n\n  constructor(options: CompressionOptions = {}) {\n    this.threshold = options.threshold || 1024; // 1KB default\n    this.level = options.level || 6; // Default compression level\n    this.encodings = options.encodings || DEFAULT_ENCODINGS;\n    this.maxInlineBytes = options.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;\n    this.filter = options.filter;\n  }\n\n  shouldCompress(req: HttpRequest, res: HttpResponse): boolean {\n    // Check custom filter\n    if (this.filter && !this.filter(req, res)) {\n      return false;\n    }\n\n    // Check if client accepts any encoding we offer\n    const acceptEncoding = (req.headers['accept-encoding'] as string) || '';\n    return negotiateEncoding(acceptEncoding, this.encodings) !== null;\n  }\n\n  wrapResponse(req: HttpRequest, res: HttpResponse): void {\n    const originalSend = res.send;\n    const acceptEncoding = (req.headers['accept-encoding'] as string) || '';\n    const level = this.level;\n    const threshold = this.threshold;\n    const encodings = this.encodings;\n    const maxInline = this.maxInlineBytes;\n    const filterOk = this.filter ? this.filter(req, res) : true;\n\n    const compressResponse = (data: any, isJson: boolean, contentType?: string) => {\n      const content = isJson ? JSON.stringify(data) : data;\n      const byteLength = Buffer.isBuffer(content)\n        ? content.length\n        : Buffer.byteLength(content ?? '');\n      const ctHeader =\n        contentType ??\n        (res.getHeader ? (res.getHeader('content-type') as string | undefined) : undefined);\n      const encoding = filterOk ? negotiateEncoding(acceptEncoding, encodings) : null;\n\n      // Skip compression when: below threshold, client accepts nothing we\n      // offer, or the content type isn't worth compressing (already-compressed\n      // binary - images, video, octet-stream). For JSON we already have the\n      // serialized string; ending with it here avoids re-entering res.json,\n      // which would JSON.stringify the same data a second time.\n      if (byteLength < threshold || !encoding || !isCompressible(ctHeader)) {\n        if (isJson) {\n          if (res.headersSent) return;\n          res.setHeader('Content-Length', byteLength);\n          res.end(content);\n          return;\n        }\n        return originalSend.call(res, data);\n      }\n\n      const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content ?? '');\n\n      // A small body is compressed here and now: cheaper than the round trip\n      // through the threadpool, and the response carries a Content-Length\n      // instead of streaming chunked. A failure falls back to the plain body.\n      if (maxInline > 0 && byteLength <= maxInline && !res.headersSent) {\n        let compressed: Buffer;\n        try {\n          compressed = compressBufferSync(buffer, encoding, level);\n        } catch {\n          if (isJson) {\n            res.setHeader('Content-Length', byteLength);\n            res.end(content);\n            return;\n          }\n          return originalSend.call(res, data);\n        }\n        res.setHeader('Content-Encoding', encoding);\n        const vary = res.getHeader ? (res.getHeader('vary') as string | undefined) : undefined;\n        res.setHeader('Vary', vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding');\n        res.setHeader('Content-Length', compressed.length);\n        res.end(compressed);\n        return res;\n      }\n\n      // Commit the response headers synchronously, BEFORE the asynchronous\n      // compression. This marks headersSent the moment send/json is called, so\n      // the \"no route matched\" fallback can't 404 the response mid-compress.\n      // The compressed length isn't known yet, so the body streams (chunked).\n      if (!res.headersSent) {\n        // A Content-Length set for the uncompressed body would truncate (or\n        // hang) the compressed one; the compressed body streams chunked.\n        if (typeof (res as any).removeHeader === 'function') {\n          (res as any).removeHeader('Content-Length');\n        }\n        res.setHeader('Content-Encoding', encoding);\n        const vary = res.getHeader ? (res.getHeader('vary') as string | undefined) : undefined;\n        res.setHeader('Vary', vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding');\n        (res as any).writeHead((res as any).statusCode || 200);\n      }\n\n      compressBuffer(buffer, encoding, level)\n        .then(compressed => res.end(compressed))\n        .catch(() => res.end()); // headers already committed - can't fall back to raw\n\n      return res;\n    };\n\n    res.json = function (data: any) {\n      if (!this.getHeader('Content-Type')) {\n        this.setHeader('Content-Type', 'application/json; charset=utf-8');\n      }\n      compressResponse(data, true, 'application/json');\n      return this;\n    };\n\n    res.send = function (data: any) {\n      compressResponse(data, false);\n      return this;\n    };\n  }\n\n  getThreshold(): number {\n    return this.threshold;\n  }\n\n  getLevel(): number {\n    return this.level;\n  }\n}\n"]}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../../src/core/middleware/built-in/compression/core.ts"],"names":[],"mappings":"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","sourcesContent":["// Compression Core Logic\n//\n// The global compression middleware wraps res.json/res.send uniformly across\n// EVERY runtime (Node, uWS, HTTP/2, engine), so it is the single source of\n// response compression parity. It delegates encoding choice and content-type\n// filtering to the shared utility (utils/compression) so brotli, q-value\n// negotiation, and the compressible-type allowlist behave identically here and\n// in the per-server fallback paths.\nimport { HttpRequest, HttpResponse } from '../../../../types/http.js';\nimport {\n  compressBuffer,\n  compressBufferSync,\n  negotiateEncoding,\n  isCompressible,\n  DEFAULT_ENCODINGS,\n  DEFAULT_MAX_INLINE_BYTES,\n  type Encoding,\n  type EncoderOptions,\n} from '../../../http/utils/compression.js';\n\nexport interface CompressionOptions extends EncoderOptions {\n  threshold?: number;\n  /** 1-9: the gzip level, and the brotli quality it maps to (see `gzip` / `brotli` to pin either). */\n  level?: number;\n  encodings?: Encoding[];\n  /**\n   * Bodies at or below this size are compressed on the calling thread and\n   * sent with a Content-Length; larger ones go to the threadpool and stream\n   * chunked. 0 sends every body through the pool. Default 16384.\n   */\n  maxInlineBytes?: number;\n  filter?: (req: HttpRequest, res: HttpResponse) => boolean;\n}\n\nexport class CompressionCore {\n  private threshold: number;\n  private level: number;\n  private encodings: Encoding[];\n  private maxInlineBytes: number;\n  private encoders: EncoderOptions;\n  private filter?: ((req: HttpRequest, res: HttpResponse) => boolean) | undefined;\n\n  constructor(options: CompressionOptions = {}) {\n    this.threshold = options.threshold || 1024; // 1KB default\n    this.level = options.level || 6; // Default compression level\n    this.encodings = options.encodings || DEFAULT_ENCODINGS;\n    this.maxInlineBytes = options.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;\n    this.encoders = {\n      ...(options.gzip !== undefined ? { gzip: options.gzip } : {}),\n      ...(options.brotli !== undefined ? { brotli: options.brotli } : {}),\n      ...(options.reuseEncoders !== undefined ? { reuseEncoders: options.reuseEncoders } : {}),\n    };\n    this.filter = options.filter;\n  }\n\n  shouldCompress(req: HttpRequest, res: HttpResponse): boolean {\n    // Check custom filter\n    if (this.filter && !this.filter(req, res)) {\n      return false;\n    }\n\n    // Check if client accepts any encoding we offer\n    const acceptEncoding = (req.headers['accept-encoding'] as string) || '';\n    return negotiateEncoding(acceptEncoding, this.encodings) !== null;\n  }\n\n  wrapResponse(req: HttpRequest, res: HttpResponse): void {\n    const originalSend = res.send;\n    const acceptEncoding = (req.headers['accept-encoding'] as string) || '';\n    const level = this.level;\n    const threshold = this.threshold;\n    const encodings = this.encodings;\n    const maxInline = this.maxInlineBytes;\n    const encoders = this.encoders;\n    const filterOk = this.filter ? this.filter(req, res) : true;\n\n    const compressResponse = (data: any, isJson: boolean, contentType?: string) => {\n      const content = isJson ? JSON.stringify(data) : data;\n      const byteLength = Buffer.isBuffer(content)\n        ? content.length\n        : Buffer.byteLength(content ?? '');\n      const ctHeader =\n        contentType ??\n        (res.getHeader ? (res.getHeader('content-type') as string | undefined) : undefined);\n      const encoding = filterOk ? negotiateEncoding(acceptEncoding, encodings) : null;\n\n      // Skip compression when: below threshold, client accepts nothing we\n      // offer, or the content type isn't worth compressing (already-compressed\n      // binary - images, video, octet-stream). For JSON we already have the\n      // serialized string; ending with it here avoids re-entering res.json,\n      // which would JSON.stringify the same data a second time.\n      if (byteLength < threshold || !encoding || !isCompressible(ctHeader)) {\n        if (isJson) {\n          if (res.headersSent) return;\n          res.setHeader('Content-Length', byteLength);\n          res.end(content);\n          return;\n        }\n        return originalSend.call(res, data);\n      }\n\n      const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content ?? '');\n\n      // A small body is compressed here and now: cheaper than the round trip\n      // through the threadpool, and the response carries a Content-Length\n      // instead of streaming chunked. A failure falls back to the plain body.\n      if (maxInline > 0 && byteLength <= maxInline && !res.headersSent) {\n        let compressed: Buffer;\n        try {\n          compressed = compressBufferSync(buffer, encoding, level, encoders);\n        } catch {\n          if (isJson) {\n            res.setHeader('Content-Length', byteLength);\n            res.end(content);\n            return;\n          }\n          return originalSend.call(res, data);\n        }\n        res.setHeader('Content-Encoding', encoding);\n        const vary = res.getHeader ? (res.getHeader('vary') as string | undefined) : undefined;\n        res.setHeader('Vary', vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding');\n        res.setHeader('Content-Length', compressed.length);\n        res.end(compressed);\n        return res;\n      }\n\n      // Commit the response headers synchronously, BEFORE the asynchronous\n      // compression. This marks headersSent the moment send/json is called, so\n      // the \"no route matched\" fallback can't 404 the response mid-compress.\n      // The compressed length isn't known yet, so the body streams (chunked).\n      if (!res.headersSent) {\n        // A Content-Length set for the uncompressed body would truncate (or\n        // hang) the compressed one; the compressed body streams chunked.\n        if (typeof (res as any).removeHeader === 'function') {\n          (res as any).removeHeader('Content-Length');\n        }\n        res.setHeader('Content-Encoding', encoding);\n        const vary = res.getHeader ? (res.getHeader('vary') as string | undefined) : undefined;\n        res.setHeader('Vary', vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding');\n        (res as any).writeHead((res as any).statusCode || 200);\n      }\n\n      compressBuffer(buffer, encoding, level, encoders)\n        .then(compressed => res.end(compressed))\n        .catch(() => res.end()); // headers already committed - can't fall back to raw\n\n      return res;\n    };\n\n    res.json = function (data: any) {\n      // The same type res.json sends without the middleware: JSON is UTF-8 by\n      // definition (RFC 8259 §8.1), so a charset parameter only adds bytes to\n      // every reply.\n      if (!this.getHeader('Content-Type')) {\n        this.setHeader('Content-Type', 'application/json');\n      }\n      compressResponse(data, true, 'application/json');\n      return this;\n    };\n\n    res.send = function (data: any) {\n      compressResponse(data, false);\n      return this;\n    };\n  }\n\n  getThreshold(): number {\n    return this.threshold;\n  }\n\n  getLevel(): number {\n    return this.level;\n  }\n}\n"]}

package/dist/core/middleware/built-in/static/core.d.ts

@@ -1,4 +1,31 @@
 import { HttpRequest, HttpResponse } from '../../../../types/http.js';
+export interface StaticCacheOptions {
+    /**
+     * Largest file kept in memory, in bytes. Bigger files take the uncached
+     * path (read or streamed from disk per request). Default 1 MiB.
+     */
+    maxFileBytes?: number;
+    /**
+     * Budget for everything cached, in bytes, originals and precompressed
+     * sidecars together; the oldest entries leave when it is exceeded.
+     * Default 64 MiB.
+     */
+    maxBytes?: number;
+    /**
+     * How long a cached file is served without looking at the disk again, in
+     * milliseconds. Past it, the next request stats the file (and the
+     * sidecars it may have) and reloads what changed, so a replaced file is
+     * served within this window at the latest. Default 1000. `0` stats on
+     * every request.
+     */
+    revalidateMs?: number;
+    /**
+     * Watch the root directory and revalidate everything the moment a change
+     * is reported, ahead of `revalidateMs`. Default true where the platform
+     * supports it; a watcher that cannot be started is simply not used.
+     */
+    watch?: boolean;
+}
 export interface StaticOptions {
     root: string;
     /**
@@ -32,6 +59,17 @@ export interface StaticOptions {
      * Range requests always get the identity file. Default false.
      */
     precompressed?: boolean;
+    /**
+     * Keep the files in memory. Without it every request resolves, stats and
+     * reads the file (and its sidecars) from disk - five to eight filesystem
+     * round trips through the threadpool per response, which is what bounds a
+     * busy static route. With it, a file is read once and served from memory
+     * with its validators and sidecars; the disk is consulted again at most
+     * once per `revalidateMs` (default every second) or as soon as the root
+     * directory reports a change, so a replaced file is still served promptly.
+     * `true` takes the defaults; an object tunes them. Default false.
+     */
+    cache?: boolean | StaticCacheOptions;
 }
 export declare class StaticCore {
     private root;
@@ -45,9 +83,59 @@ export declare class StaticCore {
     private precompressed;
     /** Files at or below this size are read in one go instead of streamed. */
     private static readonly STREAM_THRESHOLD;
+    private cache;
+    private cacheMaxFileBytes;
+    private cacheMaxBytes;
+    private cacheRevalidateMs;
+    private cacheBytes;
+    private watcher;
+    private watchWanted;
     private mimeTypes;
     constructor(options: StaticOptions);
     handleRequest(req: HttpRequest, res: HttpResponse): Promise<boolean>;
+    /**
+     * Read the file and whichever current sidecars exist beside it into one
+     * entry. Null when the file could not be read (gone between stat and
+     * read), in which case the request takes the uncached path's answer.
+     */
+    private buildEntry;
+    /** The sidecar at `candidate` when it is a regular file inside the root. */
+    private statSidecar;
+    /**
+     * Whether the disk still matches the entry: the original and every sidecar
+     * position (present or absent when the entry was built) are stat'ed and
+     * compared on mtime, size and inode, so a same-length replacement counts
+     * as a change and a sidecar that appeared or vanished does too.
+     */
+    private stillCurrent;
+    private insert;
+    private evict;
+    /**
+     * One watcher on the root directory: any change reported there marks every
+     * entry for revalidation on its next request, ahead of `revalidateMs`.
+     * Non-persistent, so it never keeps the process alive, and best effort: a
+     * platform or filesystem without change events simply falls back to the
+     * timed revalidation.
+     */
+    private ensureWatcher;
+    /** Stop the directory watcher and drop every cached file. */
+    close(): void;
+    /** Answer a request from a cache entry: the same headers and bytes the uncached path sends. */
+    private serveCached;
+    /**
+     * The identity body of a small file. A compressible one goes through
+     * send() so it joins the server's response compression (the compression
+     * middleware or performance.compression) exactly like a handler's body
+     * would; send() sets Content-Length itself. Binary bodies are ended as they
+     * are, with their length.
+     */
+    private sendBody;
+    /**
+     * The strong ETag of one representation: the file's mtime and size, plus
+     * the encoding for a sidecar, since a strong ETag must differ between
+     * representations (RFC 9110 8.8.1).
+     */
+    private static etagFor;
     /**
      * The best precompressed sidecar for `filePath` that the client accepts, or
      * null. A sidecar must be a regular file INSIDE the root (its real path is

package/dist/core/middleware/built-in/static/core.js

@@ -1,5 +1,5 @@
 import * as fs from 'fs/promises';
-import { createReadStream } from 'fs';
+import { createReadStream, watch as watchDir } from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { isCompressible, negotiateEncoding } from '../../../http/utils/compression.js';
@@ -8,6 +8,13 @@ const SIDECARS = [
     { encoding: 'br', suffix: '.br' },
     { encoding: 'gzip', suffix: '.gz' },
 ];
+const stampOf = (st) => ({
+    mtimeMs: st.mtimeMs,
+    size: st.size,
+    ino: st.ino,
+});
+const sameStamp = (a, b) => a === b ||
+    (a !== null && b !== null && a.mtimeMs === b.mtimeMs && a.size === b.size && a.ino === b.ino);
 export class StaticCore {
     root;
     prefix;
@@ -20,6 +27,15 @@ export class StaticCore {
     precompressed;
     /** Files at or below this size are read in one go instead of streamed. */
     static STREAM_THRESHOLD = 512 * 1024;
+    // The in-memory cache (see StaticOptions.cache), keyed by the request path
+    // under the prefix. Null when caching is off.
+    cache = null;
+    cacheMaxFileBytes = 1024 * 1024;
+    cacheMaxBytes = 64 * 1024 * 1024;
+    cacheRevalidateMs = 1000;
+    cacheBytes = 0;
+    watcher = null;
+    watchWanted = true;
     mimeTypes = {
         // Documents / text
         '.html': 'text/html',
@@ -90,6 +106,17 @@ export class StaticCore {
         this.lastModified = options.lastModified !== false;
         this.acceptRanges = options.acceptRanges !== false;
         this.precompressed = options.precompressed === true;
+        if (options.cache) {
+            const c = typeof options.cache === 'object' ? options.cache : {};
+            this.cache = new Map();
+            if (c.maxFileBytes !== undefined)
+                this.cacheMaxFileBytes = Math.max(0, c.maxFileBytes);
+            if (c.maxBytes !== undefined)
+                this.cacheMaxBytes = Math.max(0, c.maxBytes);
+            if (c.revalidateMs !== undefined)
+                this.cacheRevalidateMs = Math.max(0, c.revalidateMs);
+            this.watchWanted = c.watch !== false;
+        }
     }
     async handleRequest(req, res) {
         // Only handle GET and HEAD requests
@@ -101,6 +128,26 @@ export class StaticCore {
         if (urlPath === null) {
             return false;
         }
+        // Cached: the common case is a hit that needs no filesystem call at all.
+        // A Range request keeps the uncached path (byte offsets refer to the
+        // identity file on disk).
+        const cache = this.cache;
+        if (cache !== null) {
+            const entry = cache.get(urlPath);
+            if (entry !== undefined && req.headers.range === undefined) {
+                if (Date.now() - entry.checkedAt < this.cacheRevalidateMs) {
+                    return this.serveCached(req, res, entry);
+                }
+                // Past the revalidation window: one look at the disk. Unchanged, the
+                // entry serves on; changed or gone, it is dropped and the request
+                // takes the resolving path below, which rebuilds it.
+                if (await this.stillCurrent(entry)) {
+                    entry.checkedAt = Date.now();
+                    return this.serveCached(req, res, entry);
+                }
+                this.evict(urlPath, entry);
+            }
+        }
         try {
             let filePath = path.join(this.root, urlPath);
             // Security: prevent directory traversal. The trailing separator is required —
@@ -167,6 +214,18 @@ export class StaticCore {
             const ext = path.extname(filePath);
             const baseMimeType = this.mimeTypes[ext.toLowerCase()] || 'application/octet-stream';
             const contentType = this.addCharsetIfNeeded(baseMimeType);
+            // A file that fits the cache is read once, with its sidecars, and the
+            // response comes from the entry - this request's and every later one's.
+            if (cache !== null &&
+                stats.isFile() &&
+                stats.size <= this.cacheMaxFileBytes &&
+                req.headers.range === undefined) {
+                const entry = await this.buildEntry(filePath, stats, baseMimeType, contentType);
+                if (entry !== null) {
+                    this.insert(urlPath, entry);
+                    return this.serveCached(req, res, entry);
+                }
+            }
             res.setHeader('Content-Type', contentType);
             // Precompressed sidecar (app.js.br / app.js.gz next to app.js). Chosen
             // before the validators so the ETag names the encoded representation;
@@ -194,10 +253,7 @@ export class StaticCore {
             if (this.etag) {
                 // A strong ETag must differ between representations, so the encoded
                 // sidecar gets its own (RFC 9110 8.8.1)
-                etag = `"${crypto
-                    .createHash('md5')
-                    .update(`${stats.mtime.getTime()}-${stats.size}`)
-                    .digest('hex')}${sidecar ? `-${sidecar.encoding}` : ''}"`;
+                etag = StaticCore.etagFor(stats, sidecar ? sidecar.encoding : '');
                 res.setHeader('ETag', etag);
             }
             // Conditional requests. Content-Length is deliberately not set for a 304 —
@@ -256,16 +312,7 @@ export class StaticCore {
             // doesn't cost its full size in resident memory per request.
             if (stats.size <= StaticCore.STREAM_THRESHOLD || !StaticCore.canStream(res)) {
                 const data = await fs.readFile(filePath);
-                if (isCompressible(baseMimeType) && typeof res.send === 'function') {
-                    // Through send() the body joins the server's response compression
-                    // (performance.compression / the compression middleware) exactly
-                    // like a handler's body would; send() sets Content-Length itself.
-                    res.send(data);
-                }
-                else {
-                    res.setHeader('Content-Length', stats.size);
-                    res.end(data);
-                }
+                this.sendBody(res, data, baseMimeType);
             }
             else {
                 res.setHeader('Content-Length', stats.size);
@@ -278,6 +325,265 @@ export class StaticCore {
             return true;
         }
     }
+    // ---- the in-memory cache ----
+    /**
+     * Read the file and whichever current sidecars exist beside it into one
+     * entry. Null when the file could not be read (gone between stat and
+     * read), in which case the request takes the uncached path's answer.
+     */
+    async buildEntry(filePath, stats, baseMimeType, contentType) {
+        let body;
+        try {
+            body = await fs.readFile(filePath);
+        }
+        catch {
+            return null;
+        }
+        const stamp = stampOf(stats);
+        const identity = {
+            encoding: '',
+            path: filePath,
+            stamp,
+            body,
+            etag: StaticCore.etagFor(stats, ''),
+        };
+        const sidecars = [];
+        const sidecarStamps = [];
+        let bytes = body.length;
+        if (this.precompressed) {
+            const rootWithSep = this.root.endsWith(path.sep) ? this.root : this.root + path.sep;
+            for (const { encoding, suffix } of SIDECARS) {
+                const found = await this.statSidecar(filePath + suffix, rootWithSep);
+                sidecarStamps.push(found ? stampOf(found.stats) : null);
+                // A sidecar older than its source is a stale body for a replaced
+                // asset: not served, and its stamp is still remembered so a later
+                // touch of it is noticed.
+                if (!found || found.stats.mtimeMs < stats.mtimeMs)
+                    continue;
+                let sideBody;
+                try {
+                    sideBody = await fs.readFile(found.real);
+                }
+                catch {
+                    continue;
+                }
+                sidecars.push({
+                    encoding,
+                    path: found.real,
+                    stamp: stampOf(found.stats),
+                    body: sideBody,
+                    etag: StaticCore.etagFor(stats, encoding),
+                });
+                bytes += sideBody.length;
+            }
+        }
+        return {
+            filePath,
+            baseMimeType,
+            contentType,
+            mtime: stats.mtime,
+            lastModified: stats.mtime.toUTCString(),
+            identity,
+            sidecars,
+            sidecarStamps,
+            bytes,
+            checkedAt: Date.now(),
+        };
+    }
+    /** The sidecar at `candidate` when it is a regular file inside the root. */
+    async statSidecar(candidate, rootWithSep) {
+        try {
+            const real = await fs.realpath(candidate);
+            if (!real.startsWith(rootWithSep))
+                return null;
+            const stats = await fs.stat(real);
+            if (!stats.isFile())
+                return null;
+            return { real, stats };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Whether the disk still matches the entry: the original and every sidecar
+     * position (present or absent when the entry was built) are stat'ed and
+     * compared on mtime, size and inode, so a same-length replacement counts
+     * as a change and a sidecar that appeared or vanished does too.
+     */
+    async stillCurrent(entry) {
+        let stats;
+        try {
+            stats = await fs.stat(entry.filePath);
+        }
+        catch {
+            return false;
+        }
+        if (!stats.isFile() || !sameStamp(stampOf(stats), entry.identity.stamp))
+            return false;
+        if (this.precompressed) {
+            for (let i = 0; i < SIDECARS.length; i++) {
+                let now = null;
+                try {
+                    const st = await fs.stat(entry.filePath + SIDECARS[i].suffix);
+                    if (st.isFile())
+                        now = stampOf(st);
+                }
+                catch {
+                    // absent
+                }
+                if (!sameStamp(now, entry.sidecarStamps[i] ?? null))
+                    return false;
+            }
+        }
+        return true;
+    }
+    insert(key, entry) {
+        const cache = this.cache;
+        if (cache === null)
+            return;
+        const old = cache.get(key);
+        if (old !== undefined)
+            this.evict(key, old);
+        cache.set(key, entry);
+        this.cacheBytes += entry.bytes;
+        // Over budget: the oldest entries go first (insertion order).
+        for (const [k, e] of cache) {
+            if (this.cacheBytes <= this.cacheMaxBytes || k === key)
+                break;
+            this.evict(k, e);
+        }
+        this.ensureWatcher();
+    }
+    evict(key, entry) {
+        if (this.cache !== null && this.cache.delete(key))
+            this.cacheBytes -= entry.bytes;
+    }
+    /**
+     * One watcher on the root directory: any change reported there marks every
+     * entry for revalidation on its next request, ahead of `revalidateMs`.
+     * Non-persistent, so it never keeps the process alive, and best effort: a
+     * platform or filesystem without change events simply falls back to the
+     * timed revalidation.
+     */
+    ensureWatcher() {
+        if (!this.watchWanted || this.watcher !== null)
+            return;
+        try {
+            const watcher = watchDir(this.root, { persistent: false }, () => {
+                if (this.cache === null)
+                    return;
+                for (const entry of this.cache.values())
+                    entry.checkedAt = 0;
+            });
+            watcher.on('error', () => {
+                this.watcher = null;
+                this.watchWanted = false; // a dead watcher is not retried
+            });
+            this.watcher = watcher;
+        }
+        catch {
+            this.watchWanted = false;
+        }
+    }
+    /** Stop the directory watcher and drop every cached file. */
+    close() {
+        if (this.watcher !== null) {
+            try {
+                this.watcher.close();
+            }
+            catch {
+                // already closed
+            }
+            this.watcher = null;
+        }
+        if (this.cache !== null) {
+            this.cache.clear();
+            this.cacheBytes = 0;
+        }
+    }
+    /** Answer a request from a cache entry: the same headers and bytes the uncached path sends. */
+    serveCached(req, res, entry) {
+        res.setHeader('Content-Type', entry.contentType);
+        let variant = entry.identity;
+        if (this.precompressed) {
+            res.setHeader('Vary', 'Accept-Encoding');
+            const sidecars = entry.sidecars;
+            if (sidecars.length > 0) {
+                const acceptEncoding = req.headers['accept-encoding'];
+                if (acceptEncoding) {
+                    for (let i = 0; i < sidecars.length; i++) {
+                        const candidate = sidecars[i];
+                        if (negotiateEncoding(acceptEncoding, [candidate.encoding]) !== null) {
+                            variant = candidate;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        if (this.maxAge > 0) {
+            res.setHeader('Cache-Control', `public, max-age=${this.maxAge}`);
+        }
+        if (this.lastModified) {
+            res.setHeader('Last-Modified', entry.lastModified);
+        }
+        if (this.acceptRanges) {
+            res.setHeader('Accept-Ranges', 'bytes');
+        }
+        const etag = this.etag ? variant.etag : undefined;
+        if (etag !== undefined)
+            res.setHeader('ETag', etag);
+        if (this.isNotModified(req, entry.mtime, etag)) {
+            res.statusCode = 304;
+            res.end();
+            return true;
+        }
+        if (variant.encoding !== '') {
+            res.setHeader('Content-Encoding', variant.encoding);
+            res.setHeader('Content-Length', variant.body.length);
+            if (req.method === 'HEAD') {
+                res.end();
+                return true;
+            }
+            res.end(variant.body);
+            return true;
+        }
+        if (req.method === 'HEAD') {
+            res.setHeader('Content-Length', variant.body.length);
+            res.end();
+            return true;
+        }
+        this.sendBody(res, variant.body, entry.baseMimeType);
+        return true;
+    }
+    /**
+     * The identity body of a small file. A compressible one goes through
+     * send() so it joins the server's response compression (the compression
+     * middleware or performance.compression) exactly like a handler's body
+     * would; send() sets Content-Length itself. Binary bodies are ended as they
+     * are, with their length.
+     */
+    sendBody(res, data, baseMimeType) {
+        if (isCompressible(baseMimeType) && typeof res.send === 'function') {
+            res.send(data);
+        }
+        else {
+            res.setHeader('Content-Length', data.length);
+            res.end(data);
+        }
+    }
+    /**
+     * The strong ETag of one representation: the file's mtime and size, plus
+     * the encoding for a sidecar, since a strong ETag must differ between
+     * representations (RFC 9110 8.8.1).
+     */
+    static etagFor(stats, encoding) {
+        return `"${crypto
+            .createHash('md5')
+            .update(`${Math.trunc(stats.mtimeMs)}-${stats.size}`)
+            .digest('hex')}${encoding ? `-${encoding}` : ''}"`;
+    }
     /**
      * The best precompressed sidecar for `filePath` that the client accepts, or
      * null. A sidecar must be a regular file INSIDE the root (its real path is