Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koajs/cash
HTTP response caching for Koa. Supports Redis, in-memory store, and more!
https://github.com/koajs/cash
amazon aws cache caching cdn content delivery javascript koa memory network node redis s3 session sessions space static storage store
Last synced: 2 months ago
JSON representation
HTTP response caching for Koa. Supports Redis, in-memory store, and more!
- Host: GitHub
- URL: https://github.com/koajs/cash
- Owner: koajs
- License: mit
- Created: 2014-06-01T12:42:11.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-07-03T19:13:28.000Z (over 1 year ago)
- Last Synced: 2024-04-14T04:06:52.172Z (8 months ago)
- Topics: amazon, aws, cache, caching, cdn, content, delivery, javascript, koa, memory, network, node, redis, s3, session, sessions, space, static, storage, store
- Language: JavaScript
- Homepage:
- Size: 880 KB
- Stars: 153
- Watchers: 8
- Forks: 21
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-koa - cash - HTTP response caching for Koa (Middleware)
- awesome-koa - koa-cash - Koa 的 HTTP 响应缓存。支持 Redis、内存存储等。   (仓库 / 中间件)
README
# koa-cash
[](https://travis-ci.org/koajs/cash)
[](https://codecov.io/gh/koajs/cash)
[](https://github.com/sindresorhus/xo)
[](https://github.com/prettier/prettier)
[](https://lass.js.org)
[](LICENSE)
[](https://npm.im/koa-cash)
> HTTP response caching for Koa. Supports Redis, in-memory store, and more!
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
Caches the response based on any arbitrary store you'd like.
* Handles JSON and stream bodies
* Handles gzip compression negotiation (if `options.compression` is set to `true` as of v4.0.0)
* Handles 304 responses
:tada: **Pairs great with [@ladjs/koa-cache-responses](https://github.com/ladjs/koa-cache-responses)** :tada:
## Install
[NPM](https://www.npmjs.com/)
```sh
npm install koa-cash
```
[Yarn](https://yarnpkg.com/)
```sh
yarn add koa-cash
```
## Usage
```js
import LRU from 'lru-cache';
import koaCash from 'koa-cash';
// ...
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,
// so this middleware will automatically serve this response from cache
if (await ctx.cashed()) return;
// set the response body here,
// and the upstream middleware will automatically cache it
ctx.body = 'hello world!';
});
```
## API
### app.use(koaCash(options))
Options are:
#### `maxAge`
Default max age (in milliseconds) for the cache if not set via `await ctx.cashed(maxAge)`.
#### `threshold`
Minimum byte size to compress response bodies. Default `1kb`.
#### `compression`
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:
```js
function hash(ctx) {
return ctx.response.url; // same as ctx.url
}
```
`ctx` is the Koa context and is also passed as an argument. By default, it caches based on the URL.
#### `get()`
Get a value from a store. Must return a Promise, which returns the cache's value, if any.
```js
function get(key, maxAge) {
return Promise;
}
```
Note that all the `maxAge` stuff must be handled by you. This module makes no opinion about it.
#### `set()`
Set a value to a store. Must return a Promise.
```js
function set(key, value, maxAge) {
return Promise;
}
```
Note: `maxAge` is set by `.cash = { maxAge }`. If it's not set, then `maxAge` will be `0`, which you should then ignore.
#### Example
Using a library like [lru-cache](https://github.com/isaacs/node-lru-cache), though this would not quite work since it doesn't allow per-key expiration times.
```js
const koaCash = require('koa-cash');
const LRU = require('lru-cache');
const cache = new LRU({
maxAge: 30000 // global max age
})
app.use(koaCash({
get (key, maxAge) {
return cache.get(key)
},
set (key, value) {
cache.set(key, value)
}
}))
```
See [@ladjs/koa-cache-responses](https://github.com/ladjs/koa-cache-responses) test folder more examples (e.g. Redis with `ioredis`).
### 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.
`maxAge` is the max age passed to `get()`.
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. (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.
## Contributors
| Name | Website |
| ---------------- | ------------------------- |
| **Jonathan Ong** | |
| **Nick Baugh** | |
## License
[MIT](LICENSE) © [Jonathan Ong](http://jongleberry.com)
## Links
* [NPM](https://www.npmjs.com/)
* [Yarn](https://yarnpkg.com/)