abstract-cache

abstract-cache

abstract-cache is a module that provides a common interface to multiple caching strategies. It allows for requiring abstract-cache everywhere while defining the strategy via a simple configuration.

abstract-cache is heavily inspired by the excellent Catbox. The decision to create abstract-cache was predicated on a desire to require implementing clients accept previously established connections in addtion to accepting configuration to create their own connections. It also seeks to allow using either the callback or async/await style of asynchronous programming.

Available Clients

• abstract-cache-mongo
• abstract-cache-redis

Example

The following example uses abstract-cache's included in-memory cache. Of note, is that the included in-memory cache is actually callback based.

const cache = requre('abstract-cache')({useAwait: true})

async function doSomething () {
  const val = await cache.get('foo')
  console.log(val)
}

cache.set('foo', 'foo', 100)
  .then(doSomething)
  .catch(console.error)

This example shows instantiating abstract-cache with a specific store that relies upon a connection to a remote system. In this example we are supplying an already existing connection to the remote system; all abstract-cache compliant clients must support this.

const cache = require('abstract-cache')({
  useAwait: true,
  driver: {
    name: 'abstract-cache-redis',
    options: {
      client: require('redis')({url: 'some.redis.url'})
    }
  }
})

async function doSomething () {
  const val = await cache.get('foo')
  console.log(val)
}

cache.set('foo', 'foo', 100)
  .then(doSomething)
  .catch(console.error)

Options

abstract-client accepts an options object with the following properties:

• useAwait (Default: false): designate that the resulting cache client should use async/await functions. When false, every method accepts a standard callback(err, result).
• client (Default: undefined): an already instantiated strategy client. In combination with useAwait the client can be wrapped accordingly. Specifying a client superceeds the driver configuration.
• driver:
  • name (Default: undefined): specifies the implementing strategy to load. The default value results in the buil-in in-memory strategy being loaded -- this is not recommended for production environments.
  • options (Default: {}): an options object to pass to the strategy while loading. The strategy should describe this object.

memclient

The included in-memory client is available as:

const memclientFactory = require('abstract-cache').memclient

It accepts an options object:

• segment (Default: abstractMemcache): the default segment in which to store items.
• maxItems (Default: 100000): the maximum number of items to keep in the cache. The backing is an LRU cache with an upper bound.

Protocol

All implementing strategies must implement the protocol described in this section.

1. The module should export a factory function (optionsObject) {}.
2. Accept an existing connection to data stores via the optionsObject.
3. Manage connections created by itself.
4. In all cases where a key is required, the key may be a simple string, or it may be an object of the format {id: 'name', segment: 'name'}. It is up to the implementing strategy to decide how to handle these keys.
5. The factory function should return an object (client) that has the following methods and properties:
   • await (boolean property): true indicates that the strategy's methods are all async functions. If false, all methods must have a callback(err, result) as the last parameter.
   • delete(key[, callback]): removes the specified item from the cache.
   • get(key[, callback]): retrieves the desired item from the cache. The returned item should be a deep copy of the stored value to prevent alterations from affecting the cache. The result should be an object with the properties:
     • item: the item the user cached.
     • stored: a Date, in Epoch milliseconds, indicating when the item was stored.
     • ttl: the remaining lifetime of the item in the cache (milliseconds).
   • has(key[, callback]): returns a boolean result indicating if the cache contains the desired key.
   • set(key, value, ttl[, callback]): stores the specified value in the cache under the specified key for the time ttl in milliseconds.
   • start([callback]) (optional): clients that require extra initialization, e.g. to start a database connection, may export this method. When present, this method must be invoked by the user before any other method. This method may be an async function at the discretion of the implementor.
   • stop([callback]) (optional): required when start() is present. This should shutdown any connections/processes started via start(). It is left to the user to invoke this method in their shutdown procedure. This method may be an async function at the discretion of the implementor.

License

MIT License