v2.md

Memory Cache

Instantiates a mutable object cache in memory. I wrote this to use as memory store to share data among components, for use with tools like RiotJS, VueJS, and native browser apps.

NOTE: Version 2 drops support for anything that doesn't supporet ES6. For version 1, which has IE8 support, visit v1 readme. Version 1 is about 10x faster, but lacks features such as observer and immutable returns.

Installation

    npm install --save memory-cache2

Usage

Instantiate

You can either pass an existing object and convert it into a cache, or you can start a brand new cache.

    const MemoryCache = require('memory-cache');

    // Empty cache
    const cache = new MemoryCache;

    // or

    // Pass obj as cache
    const cache = new MemoryCache( myObj || returnObj() );

Events

Events can be listened for or triggered on the instantiated cache object. All events return an object with at least key and value, except for reset and expire. Below are a list of what to expect:

Event Name	Values Passed	Functions triggered on
get	key - {String}: Cache key name - {String}: Path of key's value, in case when nested value - {Any}: Entire cached value subValue - {Any}: Nested value extract from name nested - {Boolean}: Whether is a nested request or not	get, getIn
set	key - {String}: Cache key name - {String}: Path of key's value, in case when nested value - {Any}: Entire cached value with - {Any}: Nested value extract from name nested - {Boolean}: Whether is a nested request or not expiresIn - {Undefined, Number}: Time when this key will expire	set, setIn
remove	key - {String}: Cache key value - {Any}: Entire cached value	remove
concat	key - {String}: Cache key name - {String}: Path of key's value, in case when nested value - {Any}: Entire cached value with - {Any}: Nested value extract from name nested - {Boolean}: Whether is a nested request or not	concat, concatIn
merge	key - {String}: Cache key name - {String}: Path of key's value, in case when nested value - {Any}: Entire cached value with - {Any}: Nested value extract from name nested - {Boolean}: Whether is a nested request or not	merge, mergeIn
expire	key - {String}: Cache key ms - {Number}: Time in miliseconds when this key will expire	expire
reset	Does not pass any values	reset

FOR EXAMPLE:

// Happens on every get or getIn
cache.on('get', function(opts) {

    fs.writeFileSync(`${opts.name}.json`, JSON.strigify(opts.value));
});

// Only happens one time
cache.one('reset', function() {

    console.warn('Cache was reset!!!');
});

---

Set

Defines key value. Returns value.

    const val = cache.set('testing', { set: true, arr: [1,2,3] }, 4000);

    // expires in 4000 ms
    // returns { set: true, arr: [1,2,3] }

Get

Returns key value.

    const val = cache.get('testing');

    // returns { set: true, arr: [1,2,3] }

    const entireCache = cache.get(true);
    // returns { testing: { set: true, arr: [1,2,3] }}

Remove

Remove key from cache.

    cache.remove('testing');

    // returns true

Reset

Resets cache object to empty object.

    cache.reset();

    // returns {}

Debug

Turns logging off or on.

    cache.debug(true);

    // cache set testing { set: true, arr: [1,2,3] }
    // cache get testing
    // cache remove testing
    // cache reset

Expire

Expire cache after a certain amount of time in miliseconds.

    cache.expire('testing', 3000);
    // Expires in 3 seconds

Set and Expire

Set the cache and expire after a certain amount of time in miliseconds.

    cache.set('testing', { value: 1 }, 3000);
    // returns { value: 1 }
    // Expires in 3 seconds

Merge

Merge objects stored in cache. Works with arrays or objects only.

    const val = cache.merge('testing', { merged: true });
    // returns { set: true, arr: [1,2,3], merged: true }

    // Example merge array

    cache.set('array', ['a', 'b', 'c']);
    // returns ['a', 'b', 'c']

    cache.merge('array', { 0: 'A', 2: 'Z'});
    // returns ['A', 'b', 'Z']

Concat

Concatenates cached array.

    cache.set('array', ['a', 'b', 'c']);
    cache.concat('array', [1,2,3]);
    // returns ['a', 'b', 'c', 1, 2, 3];

It gets better

Lets suppose we have this object in cache:

    // Set nested object
    cache.set('nested', {
        obj: {
            is: {
                set: 'yes'
            }
        },
        arr: [
            { inside: 'array' },
            { set: false }
        ]
    });

Get Nested

Crawls cache to retrieve nested cached value. Can retrieve inside objects or arrays.

    // Get in object
    cache.getIn('nested.obj.is.set');
    // returns 'yes'

    // Get in array
    cache.getIn('nested.arr.0.inside');
    // returns 'array'

Set Nested

Crawls cache to set nested cached value. Can set inside objects or arrays.

    // Set in object
    cache.setIn('nested.obj.is.set', true);
    // returns true

    // Set in array
    cache.setIn('nested.arr.1.set', 'yes');
    // returns 'yes'

Merge Nested

Crawls cache to set merge cached value. Can merge inside objects or arrays.

    // Merge in object
    cache.mergeIn('nested.obj.is', { merged: true });
    // returns { set: true, merged: true };

    // Merge in array
    cache.mergeIn('nested.arr.1', { merged: 'yes' });
    // returns { set: 'yes', merged: 'yes' }

Concat Nested

Crawls cache to concat cached value. Can concat inside objects or arrays.

    // Concat in object
    cache.concatIn('nested.arr', { newItem: true });
    // returns [{ inside: 'array' }, { set: false }, { newItem: true }]

    // Concat in array
    cache.set('array', [{ of: { arrays: [] }}]);
    cache.concatIn('array.0.of.arrays', { newItem: true });
    // returns [{ newItem: true }];

Contributing

• Include 100% test coverage.
• Must support older browsers.
• Submit an issue first for significant changes.