koa-files

A static files serving middleware for koa.

Installation

1$ npm install koa-files

API

1import { Middleware } from 'koa';
2import fs, { Stats } from 'node:fs';
3
4interface Headers {
5  [key: string]: string | string[];
6}
7
8interface IgnoreFunction {
9  (path: string): boolean | Promise<boolean>;
10}
11
12interface HeadersFunction {
13  (path: string, stats: Stats): Promise<Headers | void> | Headers | void;
14}
15
16export interface FileSystem {
17  stat: typeof fs.stat;
18  open: typeof fs.open;
19  read: typeof fs.read;
20  close: typeof fs.close;
21}
22
23export interface Options {
24  fs?: FileSystem;
25  defer?: boolean;
26  etag?: boolean;
27  acceptRanges?: boolean;
28  lastModified?: boolean;
29  highWaterMark?: number;
30  ignore?: IgnoreFunction;
31  headers?: Headers | HeadersFunction;
32}
33
34export function server(root: string, options?: Options): Middleware;

root

• Root directory string.
• Nothing above this root directory can be served.

Options

fs

• Defaults to node:fs.
• The file system to used.

defer

• Defaults to false.
• If true, serves after await next().
• Allowing any downstream middleware to respond first.

etag

• Defaults to true.
• Enable or disable etag generation.
• Use weak etag internally.
• Can be overridden by the headers.

acceptRanges

• Defaults to true.
• Enable or disable accepting ranged requests.
• Disabling this will not send Accept-Ranges and ignore the contents of the Range request header.
• Can be overridden by the headers.

lastModified

• Defaults to true.
• Enable or disable Last-Modified header.
• Use the file system's last modified value.
• Can be overridden by the headers.

highWaterMark

• Defaults to 65536 (64 KiB).
• Set the high water mark for the read stream.

ignore

• Defaults to undefined.
• Function that determines if a file should be ignored.

headers

• Defaults to undefined.
• Set headers to be sent.
• See docs: Headers in MDN.

Example

1/**
2 * @module server
3 * @license MIT
4 * @author nuintun
5 */
6
7import Koa from 'koa';
8import { server } from 'koa-files';
9
10const app = new Koa();
11const port = process.env.PORT || 80;
12
13// Static files server
14app.use(
15  server('tests', {
16    headers: {
17      'Cache-Control': 'public, max-age=31557600'
18    }
19  })
20);
21
22/**
23 * @function httpError
24 * @param {NodeJS.ErrnoException} error
25 * @returns {boolean}
26 */
27function httpError(error) {
28  return /^(EOF|EPIPE|ECANCELED|ECONNRESET|ECONNABORTED)$/i.test(error.code);
29}
30
31// Listen error event
32app.on('error', error => {
33  !httpError(error) && console.error(error);
34});
35
36// Start server
37app.listen(port, () => {
38  console.log(`> server running at: 127.0.0.1:${port}`);
39});

Features

Support multipart range and download resumption.

License

MIT