koa-cash 4.0.4 → 4.1.1

package/README.md

@@ -10,20 +10,29 @@
 
 > HTTP response caching for Koa.  Supports Redis, in-memory store, and more!
 
-
-## Table of Contents
-
-* [Features](#features)
-* [Install](#install)
-* [Usage](#usage)
-* [API](#api)
-  * [app.use(koaCash(options))](#appusekoacashoptions)
-  * [const cached = await ctx.cashed(\[maxAge\])](#const-cached--await-ctxcashedmaxage)
-* [Notes](#notes)
-* [Usage](#usage-1)
-* [Contributors](#contributors)
-* [License](#license)
-
+Table of Contents
+
+* [koa-cash](#koa-cash)
+  * [Features](#features)
+  * [Install](#install)
+  * [Usage](#usage)
+  * [API](#api)
+    * [app.use(koaCash(options))](#appusekoacashoptions)
+      * [`maxAge`](#maxage)
+      * [`threshold`](#threshold)
+      * [`compression`](#compression)
+      * [`setCachedHeader`](#setcachedheader)
+      * [`methods`](#methods)
+      * [`hash()`](#hash)
+      * [`get()`](#get)
+      * [`set()`](#set)
+      * [Example](#example)
+    * [Max age (optional)](#max-age-optional)
+    * [CashClear](#cashclear)
+  * [Notes](#notes)
+  * [Contributors](#contributors)
+  * [License](#license)
+  * [Links](#links)
 
 ## Features
 
@@ -35,30 +44,36 @@ Caches the response based on any arbitrary store you'd like.
 
 :tada: **Pairs great with [@ladjs/koa-cache-responses](https://github.com/ladjs/koa-cache-responses)** :tada:
 
-
 ## Install
 
-[npm][]:
+[NPM](https://www.npmjs.com/)
 
 ```sh
 npm install koa-cash
 ```
 
-[yarn][]:
+[Yarn](https://yarnpkg.com/)
 
 ```sh
 yarn add koa-cash
 ```
 
-
 ## Usage
 
 ```js
-const koaCash = require('koa-cash');
+import LRU from 'lru-cache';
+import koaCash from 'koa-cash';
 
 // ...
-
-app.use(koaCash())
+const cache = new LRU();
+app.use(koaCash({
+  get: (key) => {
+    return cache.get(key);
+  },
+  set(key, value) {
+    return cache.set(key, value);
+  },
+}))
 
 app.use(async ctx => {
   // this response is already cashed if `true` is returned,
@@ -71,7 +86,6 @@ app.use(async ctx => {
 });
 ```
 
-
 ## API
 
 ### app.use(koaCash(options))
@@ -90,6 +104,16 @@ Minimum byte size to compress response bodies. Default `1kb`.
 
 If a truthy value is passed, then compression will be enabled.  This value is `false` by default.
 
+#### `setCachedHeader`
+
+If a truthy value is passed, then `X-Cached-Response` header will be set as `HIT` when response is served from the cache.  This value is `false` by default.
+
+#### `methods`
+
+If an object is passed, then add extra HTTP method caching. This value is empty by default. But `GET` and `HEAD` are enabled.
+
+Eg: `{ POST: true }`
+
 #### `hash()`
 
 A hashing function. By default, it's:
@@ -150,7 +174,11 @@ app.use(koaCash({
 
 See [@ladjs/koa-cache-responses](https://github.com/ladjs/koa-cache-responses) test folder more examples (e.g. Redis with `ioredis`).
 
-### const cached = await ctx.cashed(\[maxAge])
+### Max age (optional)
+
+```js
+const cached = await ctx.cashed(maxAge) // maxAge is passed to your caching strategy
+```
 
 This is how you enable a route to be cached. If you don't call `await ctx.cashed()`, then this route will not be cached nor will it attempt to serve the request from the cache.
 
@@ -158,17 +186,20 @@ This is how you enable a route to be cached. If you don't call `await ctx.cashed
 
 If `cached` is `true`, then the current request has been served from cache and **you should early `return`**. Otherwise, continue setting `ctx.body=` and this will cache the response.
 
+### CashClear
+
+```js
+ctx.cashClear('/')
+```
+
+This is a special method available on the ctx that you can use to clear the cache for a specific key.
 
 ## Notes
 
-* Only `GET` and `HEAD` requests are cached.
+* Only `GET` and `HEAD` requests are cached. (Unless overridden)
 * Only `200` responses are cached. Don't set `304` status codes on these routes - this middleware will handle it for you
 * The underlying store should be able to handle `Date` objects as well as `Buffer` objects. Otherwise, you may have to serialize/deserialize yourself.
 
-
-## Usage
-
-
 ## Contributors
 
 | Name             | Website                   |
@@ -176,14 +207,11 @@ If `cached` is `true`, then the current request has been served from cache and *
 | **Jonathan Ong** | <http://jongleberry.com>  |
 | **Nick Baugh**   | <http://niftylettuce.com> |
 
-
 ## License
 
 [MIT](LICENSE) © [Jonathan Ong](http://jongleberry.com)
 
+## Links
 
-## 
-
-[npm]: https://www.npmjs.com/
-
-[yarn]: https://yarnpkg.com/
+* [NPM](https://www.npmjs.com/)
+* [Yarn](https://yarnpkg.com/)

package/index.js

@@ -11,13 +11,15 @@ const safeStringify = require('fast-safe-stringify');
 const compress = promisify(gzip);
 
 // methods we cache
-const methods = {
+const defaultMethods = {
   HEAD: true,
   GET: true
 };
 
 module.exports = function(options) {
-  options = options || { compression: false };
+  options = options || { compression: false, setCachedHeader: false };
+
+  const methods = Object.assign(defaultMethods, options.methods);
 
   const hash =
     options.hash ||
@@ -34,6 +36,12 @@ module.exports = function(options) {
   if (!get) throw new Error('.get not defined');
   if (!set) throw new Error('.set not defined');
 
+  // allow for manual cache clearing
+  function cashClear(key) {
+    // console.log(`Removing cache key: ${key}`);
+    set(key, false);
+  }
+
   // ctx.cashed(maxAge) => boolean
   async function cashed(maxAge) {
     // uncacheable request method
@@ -53,6 +61,7 @@ module.exports = function(options) {
     this.response.type = obj.type;
     if (obj.lastModified) this.response.lastModified = obj.lastModified;
     if (obj.etag) this.response.etag = obj.etag;
+    if (options.setCachedHeader) this.response.set('X-Cached-Response', 'HIT');
     if (this.request.fresh) {
       this.response.status = 304;
       return true;
@@ -81,6 +90,7 @@ module.exports = function(options) {
   async function middleware(ctx, next) {
     ctx.vary('Accept-Encoding');
     ctx.cashed = cashed.bind(ctx);
+    ctx.cashClear = cashClear.bind(ctx);
 
     await next();
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koa-cash",
   "description": "HTTP response caching for Koa. HTTP response caching for Koa.  Supports Redis, in-memory store, and more!",
-  "version": "4.0.4",
+  "version": "4.1.1",
   "author": "Jonathan Ong <me@jongleberry.com> (http://jongleberry.com)",
   "ava": {
     "verbose": true,
@@ -38,7 +38,6 @@
     "eslint": "6.x",
     "eslint-config-xo-lass": "latest",
     "fixpack": "latest",
-    "husky": "latest",
     "into-stream": "^5.1.1",
     "koa": "^2.12.0",
     "lint-staged": "latest",
@@ -46,19 +45,16 @@
     "nyc": "latest",
     "remark-cli": "latest",
     "remark-preset-github": "latest",
-    "supertest": "1.x",
+    "supertest": "latest",
     "xo": "0.25"
   },
   "engines": {
     "node": ">=8.3"
   },
+  "files": [
+    "index.js"
+  ],
   "homepage": "https://github.com/koajs/cash",
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged && npm test",
-      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-    }
-  },
   "keywords": [
     "alternative",
     "amazon",

package/.editorconfig

@@ -1,9 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true

package/.lintstagedrc.js

@@ -1,7 +0,0 @@
-module.exports = {
-  "*.md,!test/**/*.md": [
-    filenames => filenames.map(filename => `remark ${filename} -qfo`)
-  ],
-  'package.json': 'fixpack',
-  '*.js': 'xo --fix'
-};

package/.remarkignore

@@ -1 +0,0 @@
-test/snapshots/**/*.md

package/.travis.yml

@@ -1,9 +0,0 @@
-language: node_js
-node_js:
-  - '12'
-  - 'lts/*'
-  - 'node'
-script:
-  npm run test-coverage
-after_success:
-  npm run coverage

package/test/when-cached.js

@@ -1,86 +0,0 @@
-const LRU = require('lru-cache');
-const Koa = require('koa');
-const request = require('supertest');
-const test = require('ava');
-
-const cash = require('..');
-
-const createApp = function(c, opts) {
-  const app = new Koa();
-  app.use(
-    cash(
-      opts || {
-        get(key) {
-          return c.get(key);
-        },
-        set(key, value) {
-          return c.set(key, value);
-        },
-        compression: true
-      }
-    )
-  );
-  return app;
-};
-
-const c = new LRU();
-const date = Math.round(Date.now() / 1000);
-
-test.before.cb(t => {
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = 'lol';
-    ctx.etag = 'lol';
-    ctx.type = 'text/lol; charset=utf-8';
-    ctx.lastModified = new Date(date * 1000);
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200, t.end);
-});
-
-test.cb('when cached when the method is GET it should serve from cache', t => {
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    throw new Error('wtf');
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('Content-Type', 'text/lol; charset=utf-8')
-    .expect('Content-Encoding', 'identity')
-    .expect('ETag', '"lol"')
-    .expect('lol', t.end);
-});
-
-test.cb(
-  'when cached when the method is POST it should not serve from cache',
-  t => {
-    const app = createApp(c);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) throw new Error('wtf');
-      ctx.body = 'lol';
-    });
-
-    request(app.listen())
-      .post('/')
-      .expect(200, t.end);
-  }
-);
-
-test.cb('when cached when the response is fresh it should 304', t => {
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    throw new Error('wtf');
-  });
-
-  request(app.listen())
-    .get('/')
-    .set('If-None-Match', '"lol"')
-    .expect(304, t.end);
-});

package/test/when-not-cached.js

@@ -1,376 +0,0 @@
-const Koa = require('koa');
-const LRU = require('lru-cache');
-const intoStream = require('into-stream');
-const request = require('supertest');
-const test = require('ava');
-
-const cash = require('..');
-
-const createApp = function(c, opts) {
-  const app = new Koa();
-  app.use(
-    cash(
-      opts || {
-        get(key) {
-          return c.get(key);
-        },
-        set(key, value) {
-          return c.set(key, value);
-        },
-        compression: true
-      }
-    )
-  );
-  return app;
-};
-
-test.cb('should pass the maxAge through ctx.cash=', t => {
-  let set = false;
-
-  const c = new LRU();
-  const app = createApp(c, {
-    get(key) {
-      return c.get(key);
-    },
-    set(key, value, maxAge) {
-      set = true;
-      t.is(maxAge, 300);
-      return c.set(key, value);
-    },
-    compression: true
-  });
-
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.cash = {
-      maxAge: 300
-    };
-    ctx.body = 'lol';
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('lol', err => {
-      if (err) return t.end(err);
-
-      t.truthy(set);
-      t.is(c.get('/').body, 'lol');
-      t.end();
-    });
-});
-
-test.cb('when body is a string it should cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = 'lol';
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('lol', err => {
-      if (err) return t.end(err);
-
-      t.is(c.get('/').body, 'lol');
-      t.end();
-    });
-});
-
-test.cb('when the body is a buffer it should cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = Buffer.from('lol');
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('lol', err => {
-      if (err) return t.end(err);
-
-      t.is(c.get('/').body.toString('utf8'), 'lol');
-      t.end();
-    });
-});
-
-test.cb('when the body is JSON it should cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = {
-      message: 'hi'
-    };
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('{"message":"hi"}', err => {
-      if (err) return t.end(err);
-
-      t.is(c.get('/').body, '{"message":"hi"}');
-      t.end();
-    });
-});
-
-test.cb('when the body is a stream it should cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = intoStream('lol');
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect(200)
-    .expect('lol', err => {
-      if (err) return t.end(err);
-
-      t.is(c.get('/').body.toString('utf8'), 'lol');
-      t.end();
-    });
-});
-
-test.cb('when the type is compressible it should compress the body', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.response.type = 'text/plain';
-    ctx.body = Buffer.alloc(2048);
-  });
-
-  request(app.listen())
-    .get('/')
-    .expect('Content-Encoding', 'gzip')
-    .expect(200, err => {
-      if (err) return t.end(err);
-
-      t.truthy(c.get('/').body);
-      t.truthy(c.get('/').gzip);
-      t.is(c.get('/').type, 'text/plain; charset=utf-8');
-      t.end();
-    });
-});
-
-test.cb(
-  'when the type is compressible it should handle possible data serialisation and deserialisation',
-  t => {
-    const c = new LRU();
-    const app = createApp(c, {
-      get(key) {
-        const value = c.get(key);
-        return value && JSON.parse(value);
-      },
-      set(key, value) {
-        return c.set(key, JSON.stringify(value));
-      },
-      compression: true
-    });
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.body = new Array(1024).join('42');
-    });
-
-    const server = app.listen();
-    request(server)
-      .get('/')
-      .expect('Content-Encoding', 'gzip')
-      .expect(200, (err, res1) => {
-        if (err) return t.end(err);
-
-        request(server)
-          .get('/')
-          .expect('Content-Encoding', 'gzip')
-          .expect(200, (err, res2) => {
-            if (err) return t.end(err);
-
-            t.is(res1.text, res2.text);
-            t.end();
-          });
-      });
-  }
-);
-
-test.cb(
-  'when the type is not compressible it should not compress the body',
-  t => {
-    const c = new LRU();
-    const app = createApp(c);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.response.type = 'image/png';
-      ctx.body = Buffer.alloc(2048);
-    });
-
-    request(app.listen())
-      .get('/')
-      .expect('Content-Encoding', 'identity')
-      .expect(200, err => {
-        if (err) return t.end(err);
-
-        t.truthy(c.get('/').body);
-        t.true(!c.get('/').gzip);
-        t.is(c.get('/').type, 'image/png');
-        t.end();
-      });
-  }
-);
-
-test.cb(
-  'when the body is below the threshold it  should not compress the body',
-  t => {
-    const c = new LRU();
-    const app = createApp(c);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.body = 'lol';
-    });
-
-    request(app.listen())
-      .get('/')
-      .expect('Content-Encoding', 'identity')
-      .expect('lol')
-      .expect(200, err => {
-        if (err) return t.end(err);
-
-        t.truthy(c.get('/').body);
-        t.true(!c.get('/').gzip);
-        t.is(c.get('/').type, 'text/plain; charset=utf-8');
-        t.end();
-      });
-  }
-);
-
-test.cb('when the method is HEAD it should cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = 'lol';
-  });
-
-  request(app.listen())
-    .head('/')
-    .expect('')
-    .expect(200, err => {
-      if (err) return t.end(err);
-
-      t.is(c.get('/').body, 'lol');
-      t.is(c.get('/').type, 'text/plain; charset=utf-8');
-      t.end();
-    });
-});
-
-test.cb('when the method is POST it should not cache the response', t => {
-  const c = new LRU();
-  const app = createApp(c);
-  app.use(async function(ctx) {
-    if (await ctx.cashed()) return;
-    ctx.body = 'lol';
-  });
-
-  request(app.listen())
-    .post('/')
-    .expect('lol')
-    .expect(200, err => {
-      if (err) return t.end(err);
-
-      t.true(!c.get('/'));
-      t.end();
-    });
-});
-
-test.cb(
-  'when the response code is not 200 it should not cache the response',
-  t => {
-    const c = new LRU();
-    const app = createApp(c);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.body = 'lol';
-      ctx.status = 201;
-    });
-
-    request(app.listen())
-      .post('/')
-      .expect('lol')
-      .expect(201, err => {
-        if (err) return t.end(err);
-
-        t.true(!c.get('/'));
-        t.end();
-      });
-  }
-);
-
-test.cb(
-  'when etag and last-modified headers are set it should cache those values',
-  t => {
-    const c = new LRU();
-    const app = createApp(c);
-    const date = Math.round(Date.now() / 1000);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.body = 'lol';
-      ctx.etag = 'lol';
-      ctx.type = 'text/lol; charset=utf-8';
-      ctx.lastModified = new Date(date * 1000);
-    });
-
-    request(app.listen())
-      .get('/')
-      .expect('lol')
-      .expect(200, err => {
-        if (err) return t.end(err);
-
-        const obj = c.get('/');
-        t.truthy(obj);
-        t.is(obj.body, 'lol');
-        t.is(obj.etag, '"lol"');
-        t.is(obj.type, 'text/lol; charset=utf-8');
-        t.is(obj.lastModified.getTime(), new Date(date * 1000).getTime());
-        t.end();
-      });
-  }
-);
-
-test.cb(
-  'when the response is fresh it should return a 304 and cache the response',
-  t => {
-    const c = new LRU();
-    const app = createApp(c);
-    const date = Math.round(Date.now() / 1000);
-    app.use(async function(ctx) {
-      if (await ctx.cashed()) return;
-      ctx.body = 'lol';
-      ctx.etag = 'lol';
-      ctx.type = 'text/lol; charset=utf-8';
-      ctx.lastModified = new Date(date * 1000);
-    });
-
-    const server = app.listen();
-    request(server)
-      .get('/')
-      .set('If-None-Match', '"lol"')
-      .expect('')
-      .expect(304, err => {
-        if (err) return t.end(err);
-
-        const obj = c.get('/');
-        t.truthy(obj);
-        t.is(obj.body, 'lol');
-        t.is(obj.etag, '"lol"');
-        t.is(obj.type, 'text/lol; charset=utf-8');
-        t.is(obj.lastModified.getTime(), new Date(date * 1000).getTime());
-        t.end();
-      });
-  }
-);