Cacheiro NPM | npm.io

cacheiro

cacheiro. substantivo masculino:
Porco semental.
Levar a porca ao cacheiro.

Intro

cacheiro is the simplest -yet effective- cache manager.

Install

npm install cacheiro

Getting Started

import {cacheiro} from 'cacheiro'

const options = {
  type: 'combined', // or 'memory' or 'redis'
  redis: {
    host: '127.0.0.1', // '0.0.0.0' if in Docker
    port: 6379
  },
  namespace: 'my_cache',
  version: 1,
  clean: true,
  ttl: 86400 * 1000 * 30,
  log: 'debug'
}

const cache= await cacheiro(options)

await cache.setItem('key', 'value')
// true
await cache.hasItem('key')
// true
await cache.getKeys()
// ['key']
await cache.getItem('key')
// 'value'
await cache.unsetItem('key')
// true
await cache.getOrSetItem('key', 
  () => {
    console.log('Value is not there, let\'s create it')
    return 'value'
  } 
)
// Value is not there, let's create it
// => 'value'
await cache.unsetAll()
// 1

API

`await cacheiro(options)`

Creates and inits the cache store.

`type`

memory: cache stuff directly on memory. If you loose the variable, you lose the cache.
redis: use node-redis as caching layer. You need to pass options.redis field.
combined: combination of both memory and redis. You need to pass options.redis field. memory cache will act as a read-only replica of redis.

`redis`

Redis connection parameters. Refer to node-redis for further info.

`namespace`

Prefix to be used for all the cache keys managed by cacheiro. Default is 'cacheiro'.

`version`

Handle cached data versions to easily unvalidate previous content. Default is 1.

`clean`

If true, cache will be clean right after initialization. (It applies only to redis or combined). Default is false.

`ttl`

Expiration time in miliseconds for the cached values. They can be setted also at item level on cache.setItem(key, value, ttl). Default is 86400000, 1 day. Notice that for memory cache, ttl is handled though setTimeout. This has a limit of 32-buit integers (max ttl is 2147483647, a bit less of 25 days).

`log`

It can be a string with the log level (silly, debug, info, warn, error) or a class exposing methods named as those log levels, for example:

  log: class CustomLogger {
    _log(l, s) {
      console.log(`[${l}] ${s}`)
    }
    
    silly(s) { this.log('silly', s) }
    debug(s) { this.log('debug', s) }
    info(s)  { this.log('info', s) }
    warn(s)  { this.log('warn', s) }
    error(s) { this.log('error', s) }
  }
}

Default is debug.

`await setItem(key, value, ttl = <ms>)`

Stores a value in the cache, identified by key. If specified, ttl is the expiration time (or Time To Live) in miliseconds.

`await getItem(key)`

Returns, if exists, stored value for key. undefined otherwise.

`await hasItem(key)`

Returns true if there is some value stored for key. false otherwise.

`await unsetItem(key)`

Removes from cache any value stored for key. Returns true if there was some value stored. false otherwise.

`await getKeys(pattern)`

Returns an array of keys present in the cache and matching pattern.

`await getAll(pattern)`

Returns an object like {key: value...} of all the stuff present in the cache and matching pattern.

`await getValues(pattern)`

Returns an array of all the values present in the cache whose key is matching pattern.

`await unsetAll(pattern)`

Removes from cache all values matching pattern.

`pattern` parameter

In the case of redis or combined caches, pattern is handled by Redis.

In the case of memory cache, cacheiro will create a RegExp(pattern), unless you specify no pattern or the '*' wildcard value.

TODO

Detect Redis is installed in the system: and, if not, failback to memory cache.
memory cache and ttl: find a better expiring method than setTimeout(). Probably passing a cron through options.
memory cache and pattern: find a beter solution than RegExp. Something closer to Redis pattern's handling.

Changelog

0.3.1

instanceof redis.ReplyError causes error TypeError: Right-hand side of 'instanceof' is not an object when running inside Docker. Still dunno why. Just try-catching by now.