Nefarious Pickle Muncher

    mightycache

    3.4.4 • Public • Published

    Mighty Cache

    npm npm Build Status Coverage Status Codacy Code Climate David David David

    Module providing multiple implementations of a cache backed by a data store.

    Lead Maintainer: David Pate

    Purpose

    Mighty Cache is meant to provide an easy to use interface for caching backed by any number of data stores through implementations.

    Structure

    This section describes the overall structure of the code within the service.

    Tests

    The test directory contains multiple sets of tests which are meant to test multiple implementations for data stores. The tests use supertest to send actual requests to the server and ensure that our interfaces and implementations are working as expected and responding correctly.

    Full Example With Express

    A custom cache implementation can be used if needed, it should just use the same interface as described in the Cache Implementation section.

    var express = require('express');
    var app = express();
    var mightyCache = require('mightycache');
    var cacheImpl = mightyCache.cache('redis',
        {
            host: 'localhost',
            port: 6379,
            options: {}
        }
    );
    var handler = mightyCache.handler(cacheImpl, {
      keyFunc: function generateKey(req) {
        return req.user.username + '-cache.json';
      }
    });
     
    app.route('/cache/:username')
       .head(handler.head)
       .get(handler.restore)
       .post(handler.save)
       .delete(handler.remove);
     
    app.listen();

    Interface

    This section describes the interface to be used when communicating with Mighty Cache.

    Instantiation

    Create an instance of a given cache implementation.

    var mightyCache = require('mightycache');
    var cache = mightyCache.cache(cacheImpl, options);

    Parameters

    Name Type Description
    cacheImpl string Required. The name of the cache implementation to use.
    options object Required. The options to be used to instantiate the cache implementation.

    Create a Handler

    Create an instance of a handler for web service requests.

    var mightyCache = require('mightycache');
    var handler = mightyCache.handler(cacheImpl, options);

    Parameters

    Name Type Description
    cacheImpl object Required. The cache implementation to be used by the handler. Must implement all required methods from the cache interface.
    options object Required. The options to be used to instantiate the handler.
    options.keyFunc function Required. Function to be used to generate a key to be used as the name for operations on cached data.

    The options.keyFunc option is called with each request with the Express request object. The request object can be optionally used and it should return a string.

    Example Key Function
    function generateKey(req) {
        return req.user.username + '-cache.json';
    }

    Implementations

    Below is the list of current implementations supported and details about their required options and how to instantiate them.

    Redis

    The Redis implementation uses the redis module to establish a connection to Redis.

    var mightyCache = require('mightycache');
    var cache = mightyCache.cache('redis',
        {
            host: 'localhost',
            port: 6379,
            options: {}
        }
    );

    Parameters

    Name Type Description
    host string Required. The host to connect to establish a connection to Redis.
    port number Required. The port to connect to establish a connection to Redis.
    options object Required. Options object used to create a Redis client, see redis.createClient() for available options.

    S3

    The S3 implementation uses the module module to establish a connection to Amazon S3.

    var mightyCache = require('mightycache');
    var cache = mightyCache.cache('s3',
        {
            bucket: 'test-bucket'
        }
    );

    Parameters

    Name Type Description
    bucket string Required. Bucket to be used to store cache data in. This can include both the bucket and a path. (Ex. test-bucket/cache/data)
    accessKeyId string Optional. Access Key Id to be used to connect to S3. The AWS SDK can pull in variables dynamically.
    secretAccessKey string Optional. Secret Access Key corresponding to the provided Access Key Id to allow authentication to access S3. The AWS SDK can pull in variables dynamically.

    Memory

    The in-memory implementation which is meant for testing purposes only as it is not mature, therefore it is not production ready and it is not expected to ever be production ready.

    var mightyCache = require('mightycache');
    var cache = mightyCache.cache('mem',{});

    Parameters

    As this is meant solely for testing purposes it currently has no required parameters.

    Cache Implementation

    Every implementation must implement the following methods:

    head(key[, ifNewerHash])

    Retrieves the cached metadata for the provided key.

    • key String. Required. Identifies the item to retrieve the metadata for
    var cache = mightyCache.cache(cacheImplName, options);
    cache.restore('test-key').then(function(data) {
      // Metadata successfully retrieved, `data.etag` has the hash of the currently cached value
    }, function(reason) {
      // Something went wrong
    });

    restore(key[, ifNewerHash])

    Restores the cached data for the provided key.

    • key String. Required. Identifies the data being retrieved
    • ifNewerHash String. Optional. If provided only retrieves the cached data if the hashes do not match, otherwise it just retrieves everything
    var cache = mightyCache.cache(cacheImplName, options);
    cache.restore('test-key').then(function(data) {
      // Data successfully retrieved, `data.etag` has the hash of it and `data.body` has the data that was cached
    }, function(reason) {
      // Something went wrong
    });

    save(dataToBeCached, key[, hashToReplace])

    Stores the data for the provided key.

    • dataToBeCached String. Required. The data to be stored
    • key String. Required. Identifies the data being stored, used later to retrieve, update, or restore the cache
    • hashToReplace String Optional If provided, only updates the cache when the hash value provided is the same as what is currently stored. If there isn't a cache currently created it will persist the data regardless.
    var cache = mightyCache.cache(cacheImplName, options);
    cache.save('Test Data', 'test-key').then(function(data) {
      // Data successfully stored `data.etag` has the etag that was generated
    }, function(reason) {
      // Something went wrong
    });

    remove(key[, hashToDelete])

    Deletes the cached data for the provided key.

    • key String. Required. Identifies the data being deleted
    • hashToDelete String. Optional. If provided only deletes the cache if the hashes match, otherwise it just deletes the cache
    var cache = mightyCache.cache(cacheImplName, options);
    cache.remove('test-key').then(function() {
      // Cache successfully deleted
    }, function(reason) {
      // Something went wrong
    });

    keys()

    Returns an array of all of the saved keys in the cache or within the cache set (if called on a Set).

    var cache = mightyCache.cache(cacheImplName, options);
    cache.keys().then(function(keys) {
        // array of keys
    }, function(reason) {
        // Something went wrong
    });

    set(name)

    Creates an instance of a Set. This allows grouping many items under any given key. The Set instance supports all the methods of a Cache instance with the exception of set. You are not allowed to create a set form a set instance. Multiple sets can be created for each cache, if the same set key is requested a new one will not be create but it will be retrieve a cached set.

    • name String. Required. Name of the hash set
    var cache = mightyCache.cache(cacheImplName, options);
    cache.set('myNewSet').then(function (cacheSet) {
            cacheSet.save('Test Data', 'test-key').then(function (data) {
                // Data successfully stored `data.etag` has the etag that was generated
            }, function (reason) {
                // Something went wrong
            });
        },
        function (reason) {
            // Something went wrong
        });

    exists(key)

    Test if a key exists in the cache store.

    • key String. Required. Key of the hash set
    var cache = cacheModule.cache(cacheImplName, options);
    cache.exists(key).then(function(exists){
        true if the item exists
    })

    clear()

    Removes all items from the cache store.

    var cache = cacheModule.cache(cacheImplName, options);
    cache.clear().then(function(){
        resolved if successful
    })

    Testing

    This repository uses Mocha as its test runner. Tests can be run by executing the following command:

    npm test

    This will run all tests and report on their success/failure in the console, additionally it will include our Code Coverage.

    Code Coverage

    This repository uses Istanbul as its code coverage tool. Code Coverage can be calculated by executing the following command:

    npm test

    This will report the Code Coverage to the console similar to the following:

    =============================== Coverage summary ===============================
    Statements   : 83.05% ( 397/478 )
    Branches     : 77.84% ( 130/167 )
    Functions    : 84.85% ( 112/132 )
    Lines        : 83.05% ( 397/478 )
    ================================================================================

    Additionally, an interactive HTML report will be generated in ./coverage/lcov-report/index.html which allows browsing the coverage by file.

    Code Style

    This repository uses JSHint for static analysis, JavaScript Code Style for validating code style, JSInspect to detect code duplication, Buddy.js to detect the use of Magic Numbers, and Node Security Project for detecting potential security threats with our dependencies.

    To run the code quality tools above, simply execute the following command:

    npm run-script inspect

    This will create files with the results in the reports directory. The only exception is NSP which only outputs to the console that it is run in right now.

    License

    MIT

    Copyright

    Copyright (c) 2014 Riptide Software Inc.

    Install

    npm i mightycache

    DownloadsWeekly Downloads

    7

    Version

    3.4.4

    License

    MIT

    Last publish

    Collaborators

    • ahoran3
    • davidtpate
    • jhorlin
    • tylerdixon