Skip to content

Commit f0e252a

Browse files
julianrubischjulianrubisch
committed
Update README #6 
1 parent 27543ac commit f0e252a

File tree

1 file changed

+125
-116
lines changed

1 file changed

+125
-116
lines changed

‎README.md

Lines changed: 125 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,132 @@
1-
# express-asset-file-cache-middleware
1+
# express-asset-file-cache-middleware
22
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
33
[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
44
<!-- ALL-CONTRIBUTORS-BADGE:END -->
5-
6-
![Build Status](https://github.com/julianrubisch/express-asset-file-cache-middleware/workflows/Node%20CI/badge.svg)
7-
8-
A modest express.js middleware to locally cache assets (images, videos, audio, etc.) for faster access and proxying, for use in e.g. Electron apps.
9-
10-
## TL;DR
11-
12-
For offline use of dynamic assets, e.g. in your Electron app or local express server.
13-
14-
## Usage
15-
16-
```javascript
17-
const express = require("express");
18-
const fileCacheMiddleware = require("express-asset-file-cache-middleware");
19-
20-
const app = express();
21-
22-
app.get(
23-
"/assets/:asset_id",
24-
async (req, res, next) => {
25-
res.locals.fetchUrl = `https://cdn.example.org/path/to/actual/asset/${req.params.asset_id}`;
26-
27-
res.locals.cacheKey = `${someExpirableUniqueKey}`;
28-
next();
29-
},
30-
fileCacheMiddleware({ cacheDir: "/tmp" }),
31-
(req, res) => {
32-
res.set({
33-
"Content-Type": res.locals.contentType,
34-
"Content-Length": res.locals.contentLength
35-
});
36-
res.end(res.locals.buffer, "binary");
37-
}
38-
);
39-
40-
app.listen(3000);
41-
```
42-
43-
It works by fetching your asset in between two callbacks on e.g. a route, by attaching a `fetchUrl` onto `res.locals`. When the asset isn't cached on disk already, it will write it into a directory specified by the option `cacheDir`. If it finds a file that's alread there, it will use that.
44-
5+
6+
![Build Status](https://github.com/julianrubisch/express-asset-file-cache-middleware/workflows/Node%20CI/badge.svg)
7+
8+
A modest express.js middleware to locally cache assets (images, videos, audio, etc.) for faster access and proxying, for use in e.g. Electron apps.
9+
10+
## TL;DR
11+
12+
For offline use of dynamic assets, e.g. in your Electron app or local express server.
13+
14+
## Usage
15+
16+
```javascript
17+
const express = require("express");
18+
const fileCacheMiddleware = require("express-asset-file-cache-middleware");
19+
20+
const app = express();
21+
22+
app.get(
23+
"/assets/:asset_id",
24+
async (req, res, next) => {
25+
res.locals.fetchUrl = `https://cdn.example.org/path/to/actual/asset/${req.params.asset_id}`;
26+
27+
res.locals.cacheKey = `${someExpirableUniqueKey}`;
28+
next();
29+
},
30+
fileCacheMiddleware({ cacheDir: "/tmp", maxSize: 10 * 1024 * 1024 * 1024 }),
31+
(req, res) => {
32+
res.set({
33+
"Content-Type": res.locals.contentType,
34+
"Content-Length": res.locals.contentLength
35+
});
36+
res.end(res.locals.buffer, "binary");
37+
}
38+
);
39+
40+
app.listen(3000);
41+
```
42+
43+
It works by fetching your asset in between two callbacks on e.g. a route, by attaching a `fetchUrl` onto `res.locals`. When the asset isn't cached on disk already, it will write it into a directory specified by the option `cacheDir`. If it finds a file that's alread there, it will use that.
44+
4545
The asset's `contentType` and `contentLength` are stored base64 encoded in the filename, thus no offline database is necessary
46-
47-
Note that setting `cacheKey` and `cacheDir` isn't strictly necessary, it will fall back to `res.local.fetchUrl` and `path.join(process.cwd(), "/tmp")`, respectively.
48-
49-
## Install
50-
51-
$ npm install express-asset-file-cache-middleware
52-
53-
or
54-
55-
$ yarn add express-asset-file-cache-middleware
56-
57-
## API
58-
59-
### Input
60-
61-
#### `res.locals.fetchUrl` (required)
62-
63-
The URL of the asset to cache.
64-
65-
#### `res.locals.cacheKey` (optional)
66-
67-
A unique, expireable cache key. If your asset contains a checksum/digest, you're already done, because it falls back to `res.locals.fetchUrl`.
68-
69-
### Output
70-
71-
To further process the response, the following entries of `res.locals` are set:
72-
73-
#### `res.locals.buffer`
74-
75-
The cached asset as a binary buffer. Most likely, you will end the request chain with
76-
77-
```javascript
78-
res.end(res.locals.buffer, "binary");
79-
```
80-
81-
#### `res.locals.contentType` and `res.locals.contentLength`
82-
83-
If you're serving your assets in the response, you'll need to set
84-
85-
```javascript
86-
res.set({
87-
"Content-Type": res.locals.contentType,
88-
"Content-Length": res.locals.contentLength
89-
});
90-
```
91-
92-
## Options
93-
94-
You can pass the following options to the middleware:
95-
96-
### `cacheDir` (optional)
97-
98-
The root directory where the file cache will be located. Falls back to `path.join(process.cwd(), "/tmp")`.
99-
100-
### `logger` (optional)
101-
102-
A logger to use for debugging, e.g. Winston, console, etc.
103-
104-
## Tests
105-
106-
Run the test suite:
107-
108-
```bash
109-
# install dependencies
110-
$ npm install
111-
112-
# unit tests
113-
$ npm test
114-
```
115-
116-
## License
117-
118-
The MIT License (MIT)
119-
120-
Copyright (c) 2019 Julian Rubisch
46+
47+
Note that setting `cacheKey` and `cacheDir` isn't strictly necessary, it will fall back to `res.local.fetchUrl` and `path.join(process.cwd(), "/tmp")`, respectively.
48+
49+
## LRU Eviction
50+
51+
To avoid cluttering your device, an LRU (least recently used) cache eviction strategy in place. Per default, when your cache dir grows over 1 GB of size, the least recently used (accessed) files will be evicted (deleted), until enough disk space is available again. You can change the cache dir size by specifying `options.maxSize` (in bytes) when creating the middleware.
52+
53+
54+
## Install
55+
56+
$ npm install express-asset-file-cache-middleware
57+
58+
or
59+
60+
$ yarn add express-asset-file-cache-middleware
61+
62+
## API
63+
64+
### Input
65+
66+
#### `res.locals.fetchUrl` (required)
67+
68+
The URL of the asset to cache.
69+
70+
#### `res.locals.cacheKey` (optional)
71+
72+
A unique, expireable cache key. If your asset contains a checksum/digest, you're already done, because it falls back to `res.locals.fetchUrl`.
73+
74+
### Output
75+
76+
To further process the response, the following entries of `res.locals` are set:
77+
78+
#### `res.locals.buffer`
79+
80+
The cached asset as a binary buffer. Most likely, you will end the request chain with
81+
82+
```javascript
83+
res.end(res.locals.buffer, "binary");
84+
```
85+
86+
#### `res.locals.contentType` and `res.locals.contentLength`
87+
88+
If you're serving your assets in the response, you'll need to set
89+
90+
```javascript
91+
res.set({
92+
"Content-Type": res.locals.contentType,
93+
"Content-Length": res.locals.contentLength
94+
});
95+
```
96+
97+
## Options
98+
99+
You can pass the following options to the middleware:
100+
101+
### `cacheDir` (optional)
102+
103+
The root directory where the file cache will be located. Falls back to `path.join(process.cwd(), "/tmp")`.
104+
105+
### `logger` (optional)
106+
107+
A logger to use for debugging, e.g. Winston, console, etc.
108+
109+
### `maxSize` (optional)
110+
The maximum size of the cache directory, from which LRU eviction is applied. Defaults to 1 GB (1024 * 1024 * 1024).
111+
112+
113+
## Tests
114+
115+
Run the test suite:
116+
117+
```bash
118+
# install dependencies
119+
$ npm install
120+
121+
# unit tests
122+
$ npm test
123+
```
124+
125+
## License
126+
127+
The MIT License (MIT)
128+
129+
Copyright (c) 2019 Julian Rubisch
121130

122131
## Contributors ✨
123132

0 commit comments

Comments
 (0)