koa-files 5.0.0 → 5.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -6
- package/cjs/ReadStream.cjs +1 -1
- package/cjs/Service.cjs +1 -1
- package/cjs/index.cjs +1 -1
- package/cjs/utils/fs.cjs +1 -1
- package/cjs/utils/hash.cjs +1 -1
- package/cjs/utils/http.cjs +1 -1
- package/cjs/utils/path.cjs +1 -1
- package/cjs/utils/type.cjs +1 -1
- package/esm/ReadStream.js +1 -1
- package/esm/Service.js +1 -1
- package/esm/index.js +1 -1
- package/esm/utils/fs.js +1 -1
- package/esm/utils/hash.js +1 -1
- package/esm/utils/http.js +1 -1
- package/esm/utils/path.js +1 -1
- package/esm/utils/type.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,11 +15,32 @@
|
|
|
15
15
|
$ npm install koa-files
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import Koa from 'koa';
|
|
22
|
+
import { server } from 'koa-files';
|
|
23
|
+
|
|
24
|
+
const app = new Koa();
|
|
25
|
+
|
|
26
|
+
app.use(
|
|
27
|
+
server('public', {
|
|
28
|
+
headers: {
|
|
29
|
+
'Cache-Control': 'public, max-age=31536000, immutable'
|
|
30
|
+
}
|
|
31
|
+
})
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
app.listen(3000);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Then visit `http://127.0.0.1:3000/app.js` to serve `public/app.js`.
|
|
38
|
+
|
|
18
39
|
## API
|
|
19
40
|
|
|
20
41
|
```ts
|
|
21
42
|
import { Middleware } from 'koa';
|
|
22
|
-
import
|
|
43
|
+
import { PathLike, Stats } from 'node:fs';
|
|
23
44
|
|
|
24
45
|
interface Headers {
|
|
25
46
|
[key: string]: string | string[];
|
|
@@ -38,10 +59,21 @@ interface HeadersFunction {
|
|
|
38
59
|
}
|
|
39
60
|
|
|
40
61
|
export interface FileSystem {
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
62
|
+
close(fd: number, callback?: (error?: Error | null) => void): void;
|
|
63
|
+
read<T extends ArrayBufferView>(
|
|
64
|
+
fd: number,
|
|
65
|
+
buffer: T,
|
|
66
|
+
offset: number,
|
|
67
|
+
length: number,
|
|
68
|
+
position: number | bigint | null,
|
|
69
|
+
callback: (error: Error | null | undefined, bytesRead: number, buffer: T) => void
|
|
70
|
+
): void;
|
|
71
|
+
stat(path: PathLike, callback: (error: Error | null | undefined, stats: Stats) => void): void;
|
|
72
|
+
open(
|
|
73
|
+
path: PathLike,
|
|
74
|
+
flags: string | number | undefined,
|
|
75
|
+
callback: (error: Error | null | undefined, fd: number) => void
|
|
76
|
+
): void;
|
|
45
77
|
}
|
|
46
78
|
|
|
47
79
|
export interface Options {
|
|
@@ -62,6 +94,7 @@ export function server(root: string, options?: Options): Middleware;
|
|
|
62
94
|
|
|
63
95
|
- Root directory string.
|
|
64
96
|
- Nothing above this root directory can be served.
|
|
97
|
+
- `root` is resolved with `path.resolve`, so relative paths are based on the process working directory.
|
|
65
98
|
|
|
66
99
|
### Options
|
|
67
100
|
|
|
@@ -75,6 +108,7 @@ export function server(root: string, options?: Options): Middleware;
|
|
|
75
108
|
- Defaults to `false`.
|
|
76
109
|
- If true, serves after `await next()`.
|
|
77
110
|
- Allowing any downstream middleware to respond first.
|
|
111
|
+
- Useful when you want route handlers to take priority over static files.
|
|
78
112
|
|
|
79
113
|
##### `etag`
|
|
80
114
|
|
|
@@ -101,17 +135,28 @@ export function server(root: string, options?: Options): Middleware;
|
|
|
101
135
|
|
|
102
136
|
- Defaults to `65536` (64 KiB).
|
|
103
137
|
- Set the high water mark for the read stream.
|
|
138
|
+
- Supports function form to customize by file path and stats.
|
|
104
139
|
|
|
105
140
|
##### `ignore`
|
|
106
141
|
|
|
107
142
|
- Defaults to `undefined`.
|
|
108
143
|
- Function that determines if a file should be ignored.
|
|
144
|
+
- Return `true` to skip static serving for the current file.
|
|
109
145
|
|
|
110
146
|
##### `headers`
|
|
111
147
|
|
|
112
148
|
- Defaults to `undefined`.
|
|
113
149
|
- Set headers to be sent.
|
|
114
150
|
- See docs: [Headers in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
|
|
151
|
+
- Supports function form to compute headers dynamically.
|
|
152
|
+
|
|
153
|
+
### Behavior notes
|
|
154
|
+
|
|
155
|
+
- Only `GET` and `HEAD` requests are handled.
|
|
156
|
+
- `Range` requests are supported (including multipart range responses).
|
|
157
|
+
- Conditional requests are supported via `ETag` and `Last-Modified`.
|
|
158
|
+
- Requests containing invalid paths (e.g. null bytes) respond with `400`.
|
|
159
|
+
- Files outside `root` are never served.
|
|
115
160
|
|
|
116
161
|
## Example
|
|
117
162
|
|
|
@@ -157,9 +202,48 @@ app.listen(port, () => {
|
|
|
157
202
|
});
|
|
158
203
|
```
|
|
159
204
|
|
|
205
|
+
## More examples
|
|
206
|
+
|
|
207
|
+
### Prefer application routes first (`defer: true`)
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
app.use(async (ctx, next) => {
|
|
211
|
+
if (ctx.path === '/healthz') {
|
|
212
|
+
ctx.body = 'ok';
|
|
213
|
+
return;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
await next();
|
|
217
|
+
});
|
|
218
|
+
|
|
219
|
+
app.use(server('public', { defer: true }));
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Dynamic ignore rule
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
app.use(
|
|
226
|
+
server('public', {
|
|
227
|
+
ignore: path => path.endsWith('.map')
|
|
228
|
+
})
|
|
229
|
+
);
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Dynamic stream buffer
|
|
233
|
+
|
|
234
|
+
```ts
|
|
235
|
+
app.use(
|
|
236
|
+
server('public', {
|
|
237
|
+
highWaterMark: (path, stats) => (stats.size > 10 * 1024 * 1024 ? 256 * 1024 : 64 * 1024)
|
|
238
|
+
})
|
|
239
|
+
);
|
|
240
|
+
```
|
|
241
|
+
|
|
160
242
|
## Features
|
|
161
243
|
|
|
162
|
-
|
|
244
|
+
- Static file middleware for Koa.
|
|
245
|
+
- Supports multipart range and download resumption.
|
|
246
|
+
- Supports conditional requests (`ETag`, `Last-Modified`).
|
|
163
247
|
|
|
164
248
|
## License
|
|
165
249
|
|
package/cjs/ReadStream.cjs
CHANGED
package/cjs/Service.cjs
CHANGED
package/cjs/index.cjs
CHANGED
package/cjs/utils/fs.cjs
CHANGED
package/cjs/utils/hash.cjs
CHANGED
package/cjs/utils/http.cjs
CHANGED
package/cjs/utils/path.cjs
CHANGED
package/cjs/utils/type.cjs
CHANGED
package/esm/ReadStream.js
CHANGED
package/esm/Service.js
CHANGED
package/esm/index.js
CHANGED
package/esm/utils/fs.js
CHANGED
package/esm/utils/hash.js
CHANGED
package/esm/utils/http.js
CHANGED
package/esm/utils/path.js
CHANGED
package/esm/utils/type.js
CHANGED