@momsfriendlydevco/cache

Generic caching component.

This module is a very low-level caching component designed to store, retrieve, expire and cleanup a simple key-value storage.

var Cache = require('@momsfriendlydevco/cache');

var storage = new Cache({
    modules: ['memcached', 'mongo', 'memory'], // What modules to try to load (in order of preference)
});


// Set something (key, val, [expiry], [callback])
storage.set('myKey', 'myValue', moment().add(1, 'day'), (err, val) => ...)

// Get something (key, [fallback], callback)
storage.get('myKey', 'fallbackValue', (err, val) => ...)

// Forget something (key, [callback])
storage.unset('myKey', err => ...)

// Clean up storage, only supported by some modules ([callback])
storage.vacuume(err => ...)

// Hash something, objects also supported
storage.hash(complexObject, val => ...)

All methods may take a callback or return a promise.

Supported Caching Drivers

NOTES:

• By default MemcacheD caches 1mb slabs, see the documentation of the daemon to increase this
• While memory storage is theoretically infinite Node has a memory limit of 1.4gb by default. See the node CLI for details on how to increase this
• Some caching systems (notably MemcacheD) automatically vacuume entries
• For most modules the storage values are encoded / decoded via marshal. This means that complex JS primitives such as Dates, Sets etc. can be stored without issue. This is disabled in the case of MongoDB by default but can be enabled if needed
• When has() querying is not supported by the module a get() operation will be performed and the result mangled into a boolean instead, this ensures that all modules support has() at the expense of efficiency

API

NOTE: In all cases where [callback] is specified in the syntax, this module supports either callbacks or promise returns.

Cache([options]) (constructor)

Create a new cache handler and populate its default options.

cache.options(Object) or cache.options(key, val)

Set lots of options in the cache handler all at once or set a single key (dotted or array notation are supported).

Valid options are:

NOTES:

• All modules expose their own serialize / deserialize properties which defaults to the main properties by default. These are omitted from the above table for brevity
• The default setup for the serialize property assumes no circular references, override this if you really do need to store them - but at a major performance hit
• The MongoDB module does not serialize or deserialize by default in order to use its own storage format, set the serialize / deserialize properties to the main cache object to enable this behaviour

cache.option()

Alias of cache.options().

cache.init([callback])

Initialize the cache handler and attempt to load the modules in preference order. This function is automatically executed in the constructor if cache.settings.init is truthy.

cache.set(Object, [expiry], [callback]) or cache.set(key, value, [expiry], [callback])

Set a collection of keys or a single key with the optional expiry. The expiry value can be a date, millisecond offset, moment object or any valid timestring string.

cache.get(key|keys, [fallback], [callback])

Fetch a single value and call the callback. If the value does not exist the fallback value will be provided. If called with an array of keys the result is an object with a key/value combination. Callback is called as (err, value).

cache.unset(key|keys, [callback])

Release a single or array of keys.

cache.has(key, [callback])

Return whether we have the given key but not actually fetch it. NOTE: If the individual module does not implement this a simple get() will be performed and the return mangled into a boolean. See the compatibility tables at the top of this article to see if 'has' is supported.

cache.list(callback)

Attempt to return a list of known cache contents. Callback is called as (err, items).

Each item will have at minimum a id and created value. All other values (e.g. expiry) depend on the cache driver being used.

cache.vacuume([callback])

Attempt to clean up any left over or expired cache entries. This is only supported by some modules.

cache.destroy([callback])

Politely close all driver resource handles before shutting down. This function waits for all set operations to complete - even if you didn't attach a callback.

Debugging

This module uses the debug NPM module for debugging. To enable set the environment variable to DEBUG=cache.

For example:

DEBUG=cache node myFile.js