@comodinx/cache

Cache

@comodinx/cache is a Node.js cache helper.

Index

• Download & Install.
• How is it used?.
  • Middleware.
• Tests.

Download & Install

NPM

For use with redis

    npm install @comodinx/cache redis

For use with memory cache

    npm install @comodinx/cache memory-cache

Source code

$ git clone https://gitlab.com/comodinx/cache.git
$ cd cache
$ npm install

How is it used?

Configure

Environment variable	Value	Default value
CACHE_ENABLED	true/false	true
CACHE_TYPE	memory/redis	'memory'

Only for Redis

Environment variable	Default value	Value
CACHE_HOST	redis host	localhost
CACHE_PORT	redis port	6379

Only for API cache middleware

Environment variable	Value	Default value
CACHE_MIDDLEWARE_DURATION	number unit	'1 hour'
CACHE_HEADER_CONTROL	cache control header name	'cache-control'

const cache = require('@comodinx/cache');

// Simple usage
await cache.put('foo', 'bar');
const foo = await cache.get('foo');
console.log(foo);

// Expiration time usage
await cache.put('cash', 'yes', 100);
const cash = await cache.get('cash');
console.log('I have cash? ' + cash);

setTimeout(() => {
  const cash = await cache.get('cash');
  console.log('I have cash? ' + cash);
}, 200);

// Print on console:
//
// bar
// I have cash? yes
// I have cash? undefined

Middleware

Inspirated on apicache

API response caching middleware for Express/Node.

Simple usage

const { apicache } = require('@comodinx/cache');
const express = require('express');
const app = express();
const port = 3000;

app.use(apicache('1 hour'));

app.get('/', (req, res) => {
    res.send({ foo: 'bar' });
});

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`);
});

Or at a specific endpoint.

const { apicache } = require('@comodinx/cache');
const express = require('express');
const app = express();
const port = 3000;

app.get('/', apicache('1 hour'), (req, res) => {
    res.send({ foo: 'bar' });
});

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`);
});

Time format

{number} {unit time}

Available unit time
`m
`minute
`hour
`day
`week
`month

Available options

{
  enabled:             process.env.CACHE_ENABLED,                           // if false or undefined, turns off caching globally (useful on dev)
  defaultDuration:     process.env.CACHE_MIDDLEWARE_DURATION || '1 hour',   // should be either a number (in ms) or a string, defaults to '1 hour'
  headerCacheControl:  process.env.CACHE_HEADER_CONTROL || 'cache-control', // should be either a string, defaults to 'cache-control'
  respectCacheControl: process.env.CACHE_RESPECT_HEADER_CONTROL,            // should be either a boolean (true | 1), defaults to false
  cacheKey:            req.originalUrl || req.url,                          // should be either a strong or a function (in function case, return a string custom key), defaults to req.originalUrl || req.url
  statusCode:          {                                                    // list of status codes that should never be cached
    include: [],
    exclude: []
  },
  headerBlacklist:     []                                                   // list of headers that should never be cached
}

Other ways of use

Use apicache with custom options

app.get('/', apicache(), (req, res) => /* ... */);

// OR

app.get('/', apicache('2 hours', 'my-custom-cache-key'), (req, res) => /* ... */);

// OR

app.get(
    '/',
    apicache({
        duration: '2 hours'
        cacheKey: 'my-custom-cache-key'
    }),
    (req, res) => /* ... */
);

For only cache success responses, use apicache.ok (status code between 200 - 299)

app.get('/', apicache.ok(), (req, res) => /* ... */);

// OR

app.get('/', apicache.ok('2 hours', 'my-custom-cache-key'), (req, res) => /* ... */);

// OR

app.get(
    '/',
    apicache.ok({
        duration: '2 hours'
        cacheKey: 'my-custom-cache-key'
    }),
    (req, res) => /* ... */
);

For only cache success responses, use apicache.ok (status code between 200 - 299)

app.get('/', apicache.ok(), (req, res) => /* ... */);

// OR

app.get('/', apicache.ok('2 hours', 'my-custom-cache-key'), (req, res) => /* ... */);

// OR

app.get(
    '/',
    apicache.ok({
        duration: '2 hours'
        cacheKey: 'my-custom-cache-key'
    }),
    (req, res) => /* ... */
);

Tests

In order to see more concrete examples, I INVITE YOU TO LOOK AT THE TESTS :)

Run the unit tests

npm test