koa-files 5.0.0 → 5.0.2

package/README.md

@@ -15,11 +15,32 @@
 $ npm install koa-files
 ```
 
+## Quick start
+
+```ts
+import Koa from 'koa';
+import { server } from 'koa-files';
+
+const app = new Koa();
+
+app.use(
+  server('public', {
+    headers: {
+      'Cache-Control': 'public, max-age=31536000, immutable'
+    }
+  })
+);
+
+app.listen(3000);
+```
+
+Then visit `http://127.0.0.1:3000/app.js` to serve `public/app.js`.
+
 ## API
 
 ```ts
 import { Middleware } from 'koa';
-import fs, { Stats } from 'node:fs';
+import { PathLike, Stats } from 'node:fs';
 
 interface Headers {
   [key: string]: string | string[];
@@ -38,10 +59,21 @@ interface HeadersFunction {
 }
 
 export interface FileSystem {
-  stat: typeof fs.stat;
-  open: typeof fs.open;
-  read: typeof fs.read;
-  close: typeof fs.close;
+  close(fd: number, callback?: (error?: Error | null) => void): void;
+  read<T extends ArrayBufferView>(
+    fd: number,
+    buffer: T,
+    offset: number,
+    length: number,
+    position: number | bigint | null,
+    callback: (error: Error | null | undefined, bytesRead: number, buffer: T) => void
+  ): void;
+  stat(path: PathLike, callback: (error: Error | null | undefined, stats: Stats) => void): void;
+  open(
+    path: PathLike,
+    flags: string | number | undefined,
+    callback: (error: Error | null | undefined, fd: number) => void
+  ): void;
 }
 
 export interface Options {
@@ -62,6 +94,7 @@ export function server(root: string, options?: Options): Middleware;
 
 - Root directory string.
 - Nothing above this root directory can be served.
+- `root` is resolved with `path.resolve`, so relative paths are based on the process working directory.
 
 ### Options
 
@@ -75,6 +108,7 @@ export function server(root: string, options?: Options): Middleware;
 - Defaults to `false`.
 - If true, serves after `await next()`.
 - Allowing any downstream middleware to respond first.
+- Useful when you want route handlers to take priority over static files.
 
 ##### `etag`
 
@@ -101,17 +135,28 @@ export function server(root: string, options?: Options): Middleware;
 
 - Defaults to `65536` (64 KiB).
 - Set the high water mark for the read stream.
+- Supports function form to customize by file path and stats.
 
 ##### `ignore`
 
 - Defaults to `undefined`.
 - Function that determines if a file should be ignored.
+- Return `true` to skip static serving for the current file.
 
 ##### `headers`
 
 - Defaults to `undefined`.
 - Set headers to be sent.
 - See docs: [Headers in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
+- Supports function form to compute headers dynamically.
+
+### Behavior notes
+
+- Only `GET` and `HEAD` requests are handled.
+- `Range` requests are supported (including multipart range responses).
+- Conditional requests are supported via `ETag` and `Last-Modified`.
+- Requests containing invalid paths (e.g. null bytes) respond with `400`.
+- Files outside `root` are never served.
 
 ## Example
 
@@ -157,9 +202,48 @@ app.listen(port, () => {
 });
 ```
 
+## More examples
+
+### Prefer application routes first (`defer: true`)
+
+```ts
+app.use(async (ctx, next) => {
+  if (ctx.path === '/healthz') {
+    ctx.body = 'ok';
+    return;
+  }
+
+  await next();
+});
+
+app.use(server('public', { defer: true }));
+```
+
+### Dynamic ignore rule
+
+```ts
+app.use(
+  server('public', {
+    ignore: path => path.endsWith('.map')
+  })
+);
+```
+
+### Dynamic stream buffer
+
+```ts
+app.use(
+  server('public', {
+    highWaterMark: (path, stats) => (stats.size > 10 * 1024 * 1024 ? 256 * 1024 : 64 * 1024)
+  })
+);
+```
+
 ## Features
 
-Support multipart range and download resumption.
+- Static file middleware for Koa.
+- Supports multipart range and download resumption.
+- Supports conditional requests (`ETag`, `Last-Modified`).
 
 ## License
 

package/cjs/ReadStream.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -99,12 +99,12 @@ class ReadStream extends node_stream.Readable {
       // Change read state.
       switch (this.#readState) {
         case 0 /* ReadState.PREFIX */:
-          this.#readState = 1 /* ReadState.RANGE */;
+          this.#readState = 1; /* ReadState.RANGE */
           this.#readFileRange(fd, range, size - bytesRead);
           break;
         case 2 /* ReadState.SUFFIX */:
           this.#currentRangeIndex++;
-          this.#readState = 0 /* ReadState.PREFIX */;
+          this.#readState = 0; /* ReadState.PREFIX */
           const nextRange = this.#getRange();
           if (nextRange == null) {
             this.push(null);
@@ -147,14 +147,14 @@ class ReadStream extends node_stream.Readable {
           // file range read completed.
           if (bytesRead < size) {
             this.#bytesRead = 0;
-            this.#readState = 2 /* ReadState.SUFFIX */;
+            this.#readState = 2; /* ReadState.SUFFIX */
             this.#readPadding(fd, range, size - bytesRead);
           }
         }
       });
     } else {
       this.#bytesRead = 0;
-      this.#readState = 2 /* ReadState.SUFFIX */;
+      this.#readState = 2; /* ReadState.SUFFIX */
       this.#readPadding(fd, range, size);
     }
   }

package/cjs/Service.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -10,7 +10,6 @@
 
 'use strict';
 
-const createETag = require('etag');
 const fs = require('node:fs');
 const ReadStream = require('./ReadStream.cjs');
 const type = require('./utils/type.cjs');
@@ -23,7 +22,6 @@ function _interopDefault(e) {
   return e && e.__esModule ? e : { default: e };
 }
 
-const createETag__default = /*#__PURE__*/ _interopDefault(createETag);
 const fs__default = /*#__PURE__*/ _interopDefault(fs);
 
 /**
@@ -86,7 +84,7 @@ class Service {
       response.remove('ETag');
     } else if (!response.get('ETag')) {
       // Set weak ETag.
-      response.set('ETag', createETag__default.default(stats));
+      response.set('ETag', http.createETag(stats));
     }
     // Last-Modified.
     if (options.lastModified === false) {
@@ -165,10 +163,8 @@ class Service {
     }
     // Head request.
     if (method === 'HEAD') {
-      // Set Content-Length.
+      // Set Content-Length, koa keeps it and sends no body for HEAD.
       response.length = stats.size;
-      // Set body null
-      response.body = null;
       // File found.
       return true;
     }
@@ -176,14 +172,12 @@ class Service {
     const ranges = http.parseRanges(context, stats);
     // 416
     if (ranges === -1) {
-      // Set Content-Range.
-      response.set('Content-Range', `bytes */${stats.size}`);
-      // Unsatisfiable 416.
-      return context.throw(416);
-    }
-    // 400.
-    if (ranges === -2) {
-      return context.throw(400);
+      // koa strips all response headers on error, pass Content-Range via err.headers.
+      return context.throw(416, {
+        headers: {
+          'Content-Range': `bytes */${stats.size}`
+        }
+      });
     }
     // Set response body.
     response.body = new ReadStream.ReadStream(path$1, ranges, {

package/cjs/index.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/cjs/utils/fs.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/cjs/utils/http.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -10,9 +10,9 @@
 
 'use strict';
 
-const hash = require('./hash.cjs');
 const node_buffer = require('node:buffer');
 const parseRange = require('range-parser');
+const node_crypto = require('node:crypto');
 
 function _interopDefault(e) {
   return e && e.__esModule ? e : { default: e };
@@ -24,6 +24,7 @@ const parseRange__default = /*#__PURE__*/ _interopDefault(parseRange);
  * @module http
  */
 const SPLIT_ETAG_RE = /\s*,\s*/;
+const BOUNDARY_SCRATCH = node_buffer.Buffer.allocUnsafeSlow(24);
 const SINGLE_ETAG_RE = /^(?:W\/)?"[ !#-\x7E\x80-\xFF]+"$/;
 /**
  * @function decodeURI
@@ -37,6 +38,13 @@ function decodeURI(URI) {
     return -1;
   }
 }
+/**
+ * @function generateBoundary
+ * @description Generate a boundary string.
+ */
+function generateBoundary() {
+  return node_crypto.getRandomValues(BOUNDARY_SCRATCH).toString('base64url');
+}
 /**
  * @function isConditionalGET
  * @description Check if request is conditional GET.
@@ -50,6 +58,14 @@ function isConditionalGET({ request }) {
     request.get('If-Unmodified-Since')
   );
 }
+/**
+ * @function createETag
+ * @description Generate a weak entity tag from file stats.
+ * @param stats The file stats.
+ */
+function createETag(stats) {
+  return `W/"${stats.size.toString(16)}-${stats.mtime.getTime().toString(16)}"`;
+}
 /**
  * @function isETagMatch
  * @see https://httpwg.org/specs/rfc9110.html
@@ -58,25 +74,45 @@ function isConditionalGET({ request }) {
  * @param isIfMatch The flag of if-match.
  */
 function isETagMatch(match, etag, isIfMatch) {
+  // Trim match.
+  match = match.trim();
+  // Check If-Match.
+  if (isIfMatch && match === '*') {
+    // The condition is true if the selected representation exists.
+    return true;
+  }
   // Trim etag.
   etag = etag.trim();
   // Weak tags cannot be matched and return false.
   if (!etag || etag.startsWith('W/')) {
     return false;
   }
-  // Trim match.
-  match = match.trim();
   // Check If-Match.
   if (isIfMatch) {
-    if (match === '*') {
-      return true;
-    }
     // If-Match maybe a list of etag.
     return match.split(SPLIT_ETAG_RE).includes(etag);
   }
   // Check If-Range.
   return match === etag;
 }
+/**
+ * @function isRangeFresh
+ * @description Check if request range fresh.
+ * @param context Koa context.
+ */
+function isRangeFresh({ request, response }) {
+  const ifRange = request.get('If-Range');
+  // No If-Range.
+  if (!ifRange) {
+    return true;
+  }
+  // If-Range as modified date failed.
+  if (SINGLE_ETAG_RE.test(ifRange)) {
+    return isETagMatch(ifRange, response.get('ETag'));
+  }
+  // Check if Last-Modified is valid and equal to If-Range date
+  return Date.parse(response.get('Last-Modified')) <= Date.parse(ifRange);
+}
 /**
  * @function isPreconditionFailed
  * @description Check if request precondition failed.
@@ -99,24 +135,6 @@ function isPreconditionFailed({ request, response }) {
   // Check precondition passed.
   return false;
 }
-/**
- * @function isRangeFresh
- * @description Check if request range fresh.
- * @param context Koa context.
- */
-function isRangeFresh({ request, response }) {
-  const ifRange = request.get('If-Range');
-  // No If-Range.
-  if (!ifRange) {
-    return true;
-  }
-  // If-Range as modified date failed.
-  if (SINGLE_ETAG_RE.test(ifRange)) {
-    return isETagMatch(ifRange, response.get('ETag'));
-  }
-  // Check if Last-Modified is valid and equal to If-Range date
-  return Date.parse(response.get('Last-Modified')) <= Date.parse(ifRange);
-}
 /**
  * @function parseRanges
  * @description Parse ranges.
@@ -134,10 +152,16 @@ function parseRanges(context, stats) {
       // Parse range -1 -2 or [].
       const parsed = parseRange__default.default(size, range, { combine: true });
       // -1 signals an unsatisfiable range.
-      // -2 signals a malformed header string.
-      if (parsed === -1 || parsed === -2) {
+      if (parsed === -1) {
         return parsed;
       }
+      // -2 signals a malformed or unknown-unit range, ignore it (RFC 9110 §14.2).
+      if (parsed === -2) {
+        // Set Content-Length.
+        response.length = size;
+        // Return ranges.
+        return [{ offset: 0, length: size }];
+      }
       // Ranges ok, support multiple ranges.
       if (parsed.type === 'bytes') {
         // Set 206 status.
@@ -152,7 +176,7 @@ function parseRanges(context, stats) {
           // Parsed entries.
           const entries = parsed.entries();
           // Range boundary.
-          const boundary = `${hash.generate(32)}`;
+          const boundary = generateBoundary();
           // Multipart Content-Type.
           const contentType = `Content-Type: ${response.type}`;
           // Range suffix.
@@ -165,9 +189,7 @@ function parseRanges(context, stats) {
             const length = end - start + 1;
             const head = index > 0 ? '\r\n' : '';
             const contentRange = `Content-Range: bytes ${start}-${end}/${size}`;
-            const prefix = node_buffer.Buffer.from(
-              `${head}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`
-            );
+            const prefix = node_buffer.Buffer.from(`${head}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`);
             // Compute Content-Length
             contentLength += prefix.length + length;
             // Cache range.
@@ -200,7 +222,11 @@ function parseRanges(context, stats) {
   return [{ offset: 0, length: size }];
 }
 
+exports.createETag = createETag;
 exports.decodeURI = decodeURI;
+exports.generateBoundary = generateBoundary;
 exports.isConditionalGET = isConditionalGET;
+exports.isETagMatch = isETagMatch;
 exports.isPreconditionFailed = isPreconditionFailed;
+exports.isRangeFresh = isRangeFresh;
 exports.parseRanges = parseRanges;

package/cjs/utils/http.d.cts

@@ -16,12 +16,37 @@ export interface Range {
  * @param URI The URI to decode.
  */
 export declare function decodeURI(URI: string): string | -1;
+/**
+ * @function generateBoundary
+ * @description Generate a boundary string.
+ */
+export declare function generateBoundary(): string;
 /**
  * @function isConditionalGET
  * @description Check if request is conditional GET.
  * @param context The koa context.
  */
 export declare function isConditionalGET({ request }: Context): boolean;
+/**
+ * @function createETag
+ * @description Generate a weak entity tag from file stats.
+ * @param stats The file stats.
+ */
+export declare function createETag(stats: Stats): string;
+/**
+ * @function isETagMatch
+ * @see https://httpwg.org/specs/rfc9110.html
+ * @param match The match value.
+ * @param etag The etag value.
+ * @param isIfMatch The flag of if-match.
+ */
+export declare function isETagMatch(match: string, etag: string, isIfMatch?: boolean): boolean;
+/**
+ * @function isRangeFresh
+ * @description Check if request range fresh.
+ * @param context Koa context.
+ */
+export declare function isRangeFresh({ request, response }: Context): boolean;
 /**
  * @function isPreconditionFailed
  * @description Check if request precondition failed.
@@ -34,4 +59,4 @@ export declare function isPreconditionFailed({ request, response }: Context): bo
  * @param context The koa context.
  * @param stats The file stats.
  */
-export declare function parseRanges(context: Context, stats: Stats): -1 | -2 | Range[];
+export declare function parseRanges(context: Context, stats: Stats): -1 | Range[];

package/cjs/utils/path.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/cjs/utils/type.cjs

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/esm/ReadStream.js

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -97,12 +97,12 @@ class ReadStream extends Readable {
       // Change read state.
       switch (this.#readState) {
         case 0 /* ReadState.PREFIX */:
-          this.#readState = 1 /* ReadState.RANGE */;
+          this.#readState = 1; /* ReadState.RANGE */
           this.#readFileRange(fd, range, size - bytesRead);
           break;
         case 2 /* ReadState.SUFFIX */:
           this.#currentRangeIndex++;
-          this.#readState = 0 /* ReadState.PREFIX */;
+          this.#readState = 0; /* ReadState.PREFIX */
           const nextRange = this.#getRange();
           if (nextRange == null) {
             this.push(null);
@@ -145,14 +145,14 @@ class ReadStream extends Readable {
           // file range read completed.
           if (bytesRead < size) {
             this.#bytesRead = 0;
-            this.#readState = 2 /* ReadState.SUFFIX */;
+            this.#readState = 2; /* ReadState.SUFFIX */
             this.#readPadding(fd, range, size - bytesRead);
           }
         }
       });
     } else {
       this.#bytesRead = 0;
-      this.#readState = 2 /* ReadState.SUFFIX */;
+      this.#readState = 2; /* ReadState.SUFFIX */
       this.#readPadding(fd, range, size);
     }
   }

package/esm/Service.js

@@ -2,20 +2,19 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
  */
 
-import createETag from 'etag';
 import fs from 'node:fs';
 import { ReadStream } from './ReadStream.js';
 import { isFunction } from './utils/type.js';
 import { stat } from './utils/fs.js';
 import { resolve, extname, join } from 'node:path';
 import { unixify, isOutRoot, hasTrailingSlash } from './utils/path.js';
-import { decodeURI, isConditionalGET, isPreconditionFailed, parseRanges } from './utils/http.js';
+import { createETag, decodeURI, isConditionalGET, isPreconditionFailed, parseRanges } from './utils/http.js';
 
 /**
  * @module Service
@@ -156,10 +155,8 @@ class Service {
     }
     // Head request.
     if (method === 'HEAD') {
-      // Set Content-Length.
+      // Set Content-Length, koa keeps it and sends no body for HEAD.
       response.length = stats.size;
-      // Set body null
-      response.body = null;
       // File found.
       return true;
     }
@@ -167,14 +164,12 @@ class Service {
     const ranges = parseRanges(context, stats);
     // 416
     if (ranges === -1) {
-      // Set Content-Range.
-      response.set('Content-Range', `bytes */${stats.size}`);
-      // Unsatisfiable 416.
-      return context.throw(416);
-    }
-    // 400.
-    if (ranges === -2) {
-      return context.throw(400);
+      // koa strips all response headers on error, pass Content-Range via err.headers.
+      return context.throw(416, {
+        headers: {
+          'Content-Range': `bytes */${stats.size}`
+        }
+      });
     }
     // Set response body.
     response.body = new ReadStream(path, ranges, {

package/esm/index.js

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/esm/utils/fs.js

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/esm/utils/http.d.ts

@@ -16,12 +16,37 @@ export interface Range {
  * @param URI The URI to decode.
  */
 export declare function decodeURI(URI: string): string | -1;
+/**
+ * @function generateBoundary
+ * @description Generate a boundary string.
+ */
+export declare function generateBoundary(): string;
 /**
  * @function isConditionalGET
  * @description Check if request is conditional GET.
  * @param context The koa context.
  */
 export declare function isConditionalGET({ request }: Context): boolean;
+/**
+ * @function createETag
+ * @description Generate a weak entity tag from file stats.
+ * @param stats The file stats.
+ */
+export declare function createETag(stats: Stats): string;
+/**
+ * @function isETagMatch
+ * @see https://httpwg.org/specs/rfc9110.html
+ * @param match The match value.
+ * @param etag The etag value.
+ * @param isIfMatch The flag of if-match.
+ */
+export declare function isETagMatch(match: string, etag: string, isIfMatch?: boolean): boolean;
+/**
+ * @function isRangeFresh
+ * @description Check if request range fresh.
+ * @param context Koa context.
+ */
+export declare function isRangeFresh({ request, response }: Context): boolean;
 /**
  * @function isPreconditionFailed
  * @description Check if request precondition failed.
@@ -34,4 +59,4 @@ export declare function isPreconditionFailed({ request, response }: Context): bo
  * @param context The koa context.
  * @param stats The file stats.
  */
-export declare function parseRanges(context: Context, stats: Stats): -1 | -2 | Range[];
+export declare function parseRanges(context: Context, stats: Stats): -1 | Range[];

package/esm/utils/http.js

@@ -2,20 +2,21 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
  */
 
-import { generate } from './hash.js';
 import { Buffer } from 'node:buffer';
 import parseRange from 'range-parser';
+import { getRandomValues } from 'node:crypto';
 
 /**
  * @module http
  */
 const SPLIT_ETAG_RE = /\s*,\s*/;
+const BOUNDARY_SCRATCH = Buffer.allocUnsafeSlow(24);
 const SINGLE_ETAG_RE = /^(?:W\/)?"[ !#-\x7E\x80-\xFF]+"$/;
 /**
  * @function decodeURI
@@ -29,6 +30,13 @@ function decodeURI(URI) {
     return -1;
   }
 }
+/**
+ * @function generateBoundary
+ * @description Generate a boundary string.
+ */
+function generateBoundary() {
+  return getRandomValues(BOUNDARY_SCRATCH).toString('base64url');
+}
 /**
  * @function isConditionalGET
  * @description Check if request is conditional GET.
@@ -42,6 +50,14 @@ function isConditionalGET({ request }) {
     request.get('If-Unmodified-Since')
   );
 }
+/**
+ * @function createETag
+ * @description Generate a weak entity tag from file stats.
+ * @param stats The file stats.
+ */
+function createETag(stats) {
+  return `W/"${stats.size.toString(16)}-${stats.mtime.getTime().toString(16)}"`;
+}
 /**
  * @function isETagMatch
  * @see https://httpwg.org/specs/rfc9110.html
@@ -50,25 +66,45 @@ function isConditionalGET({ request }) {
  * @param isIfMatch The flag of if-match.
  */
 function isETagMatch(match, etag, isIfMatch) {
+  // Trim match.
+  match = match.trim();
+  // Check If-Match.
+  if (isIfMatch && match === '*') {
+    // The condition is true if the selected representation exists.
+    return true;
+  }
   // Trim etag.
   etag = etag.trim();
   // Weak tags cannot be matched and return false.
   if (!etag || etag.startsWith('W/')) {
     return false;
   }
-  // Trim match.
-  match = match.trim();
   // Check If-Match.
   if (isIfMatch) {
-    if (match === '*') {
-      return true;
-    }
     // If-Match maybe a list of etag.
     return match.split(SPLIT_ETAG_RE).includes(etag);
   }
   // Check If-Range.
   return match === etag;
 }
+/**
+ * @function isRangeFresh
+ * @description Check if request range fresh.
+ * @param context Koa context.
+ */
+function isRangeFresh({ request, response }) {
+  const ifRange = request.get('If-Range');
+  // No If-Range.
+  if (!ifRange) {
+    return true;
+  }
+  // If-Range as modified date failed.
+  if (SINGLE_ETAG_RE.test(ifRange)) {
+    return isETagMatch(ifRange, response.get('ETag'));
+  }
+  // Check if Last-Modified is valid and equal to If-Range date
+  return Date.parse(response.get('Last-Modified')) <= Date.parse(ifRange);
+}
 /**
  * @function isPreconditionFailed
  * @description Check if request precondition failed.
@@ -91,24 +127,6 @@ function isPreconditionFailed({ request, response }) {
   // Check precondition passed.
   return false;
 }
-/**
- * @function isRangeFresh
- * @description Check if request range fresh.
- * @param context Koa context.
- */
-function isRangeFresh({ request, response }) {
-  const ifRange = request.get('If-Range');
-  // No If-Range.
-  if (!ifRange) {
-    return true;
-  }
-  // If-Range as modified date failed.
-  if (SINGLE_ETAG_RE.test(ifRange)) {
-    return isETagMatch(ifRange, response.get('ETag'));
-  }
-  // Check if Last-Modified is valid and equal to If-Range date
-  return Date.parse(response.get('Last-Modified')) <= Date.parse(ifRange);
-}
 /**
  * @function parseRanges
  * @description Parse ranges.
@@ -126,10 +144,16 @@ function parseRanges(context, stats) {
       // Parse range -1 -2 or [].
       const parsed = parseRange(size, range, { combine: true });
       // -1 signals an unsatisfiable range.
-      // -2 signals a malformed header string.
-      if (parsed === -1 || parsed === -2) {
+      if (parsed === -1) {
         return parsed;
       }
+      // -2 signals a malformed or unknown-unit range, ignore it (RFC 9110 §14.2).
+      if (parsed === -2) {
+        // Set Content-Length.
+        response.length = size;
+        // Return ranges.
+        return [{ offset: 0, length: size }];
+      }
       // Ranges ok, support multiple ranges.
       if (parsed.type === 'bytes') {
         // Set 206 status.
@@ -144,7 +168,7 @@ function parseRanges(context, stats) {
           // Parsed entries.
           const entries = parsed.entries();
           // Range boundary.
-          const boundary = `${generate(32)}`;
+          const boundary = generateBoundary();
           // Multipart Content-Type.
           const contentType = `Content-Type: ${response.type}`;
           // Range suffix.
@@ -157,9 +181,7 @@ function parseRanges(context, stats) {
             const length = end - start + 1;
             const head = index > 0 ? '\r\n' : '';
             const contentRange = `Content-Range: bytes ${start}-${end}/${size}`;
-            const prefix = Buffer.from(
-              `${head}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`
-            );
+            const prefix = Buffer.from(`${head}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`);
             // Compute Content-Length
             contentLength += prefix.length + length;
             // Cache range.
@@ -192,4 +214,13 @@ function parseRanges(context, stats) {
   return [{ offset: 0, length: size }];
 }
 
-export { decodeURI, isConditionalGET, isPreconditionFailed, parseRanges };
+export {
+  createETag,
+  decodeURI,
+  generateBoundary,
+  isConditionalGET,
+  isETagMatch,
+  isPreconditionFailed,
+  isRangeFresh,
+  parseRanges
+};

package/esm/utils/path.js

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/esm/utils/type.js

@@ -2,7 +2,7 @@
  * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 5.0.0
+ * @version 5.0.2
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-files",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "A static files serving middleware for koa.",
   "type": "module",
   "sideEffects": false,
@@ -41,31 +41,11 @@
     "url": "https://github.com/nuintun/koa-files/issues"
   },
   "homepage": "https://github.com/nuintun/koa-files#readme",
-  "dependencies": {
-    "etag": "^1.8.1",
-    "range-parser": "^1.2.1",
-    "tslib": "^2.8.1"
-  },
-  "devDependencies": {
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/etag": "^1.8.4",
-    "@types/koa": "^3.0.2",
-    "@types/node": "^25.5.2",
-    "@types/range-parser": "^1.2.7",
-    "dts-paths": "^2.2.1",
-    "koa": "^3.2.0",
-    "prettier": "^3.8.1",
-    "rimraf": "^6.1.3",
-    "rollup": "^4.60.1",
-    "typescript": "^6.0.2"
-  },
-  "peerDependencies": {
-    "koa": ">=2.0.0"
-  },
   "scripts": {
     "lint": "tsc --noEmit",
     "pretest": "pnpm build",
     "clean": "node tools/clean.ts",
+    "prepublishOnly": "pnpm build",
     "test": "node --test tests/index.ts",
     "build:cjs": "rollup -c tools/rollup.cjs.ts",
     "build:esm": "rollup -c tools/rollup.esm.ts",
@@ -73,5 +53,25 @@
     "build": "pnpm clean && pnpm build:main && pnpm format",
     "format": "prettier --write . --ignore-path .prettierignore",
     "build:main": "pnpm build:cjs && pnpm build:esm && pnpm build:fix-types"
+  },
+  "dependencies": {
+    "range-parser": "^1.3.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/etag": "^1.8.4",
+    "@types/koa": "^3.0.3",
+    "@types/node": "^26.6.5",
+    "@types/range-parser": "^1.2.7",
+    "dts-paths": "^2.2.2",
+    "koa": "^3.2.1",
+    "prettier": "^3.9.10",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.64.12",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "koa": ">=2.0.0"
   }
-}
+}

package/cjs/utils/hash.cjs

@@ -1,47 +0,0 @@
-/**
- * @module koa-files
- * @package koa-files
- * @license MIT
- * @version 5.0.0
- * @author nuintun <nuintun@qq.com>
- * @description A static files serving middleware for koa.
- * @see https://github.com/nuintun/koa-files#readme
- */
-
-'use strict';
-
-const node_crypto = require('node:crypto');
-
-/**
- * @module hash
- */
-// prettier-ignore
-const CHARS = [
-    // 0-9
-    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
-    // A-M
-    'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
-    // N-Z
-    'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
-    // a-m
-    'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
-    // n-z
-    'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'
-];
-/**
- * @function generate
- * @description Generate a hash.
- * @param length The length of hash.
- */
-function generate(length) {
-  let hash = '';
-  const randomValues = node_crypto.getRandomValues(new Uint8Array(length));
-  // Create hash.
-  for (const value of randomValues) {
-    hash += CHARS[value % 62];
-  }
-  // Return hash.
-  return hash;
-}
-
-exports.generate = generate;

package/esm/utils/hash.js

@@ -1,45 +0,0 @@
-/**
- * @module koa-files
- * @package koa-files
- * @license MIT
- * @version 5.0.0
- * @author nuintun <nuintun@qq.com>
- * @description A static files serving middleware for koa.
- * @see https://github.com/nuintun/koa-files#readme
- */
-
-import { getRandomValues } from 'node:crypto';
-
-/**
- * @module hash
- */
-// prettier-ignore
-const CHARS = [
-    // 0-9
-    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
-    // A-M
-    'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
-    // N-Z
-    'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
-    // a-m
-    'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
-    // n-z
-    'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'
-];
-/**
- * @function generate
- * @description Generate a hash.
- * @param length The length of hash.
- */
-function generate(length) {
-  let hash = '';
-  const randomValues = getRandomValues(new Uint8Array(length));
-  // Create hash.
-  for (const value of randomValues) {
-    hash += CHARS[value % 62];
-  }
-  // Return hash.
-  return hash;
-}
-
-export { generate };