Simple Cache

A fast, simple and lightweight expiring key value store for modern browsers.

Question or comments please feel free to open an issue or email me at [email protected]. You can also visit the simple-cache website.

About

NOTE: SimpleCache follows semver versioning and is under active development.

Built on top of the Window.localStorage and Window.sessionStorage APIs, SimpleCache.js was a solution developed to provide an expiring semi-persistent data store for modern browsers. I've written an article explaining the how/why of SimpleCache if you're interested.

Want to Contribute or Help Out?

Feel free to head over to the GitHub page and submit comments, issues, pulls and whatever else you'd like. I plan on adding features as I need them for my own projects so if something isn't happening fast enough for you why not do it yourself? :wink:

Installation

NPM

npm i @stetsonpierce/simple-cache

CDN

<!-- Minified -->
<script src="https://cdn.jsdelivr.net/npm/@stetsonpierce/simple-cache@3/dist/simple-cache.min.js"></script>

Usage

Via Script Tag

<--! index.hmtl -->
<script src="https://cdn.jsdelivr.net/npm/@stetsonpierce/simple-cache@3/dist/simple-cache.min.js"></script>

<script>
  const cache = new SimpleCache.default();
  cache.set('someKey', 'someValue');
  console.log(cache.get('someKey')); // Logs 'someValue'
  cache.remove('someKey');
  console.log(cache.get('someKey')); // Logs null
</script>

Via JavaScript Module

// Can be used as an ES6 Module
import SimpleCache from '@stetsonpierce/simple-cache';

// Or a CommonJS Module
const SimpleCache = require('@stetsonpierce/simple-cache');

const cache = new SimpleCache();

cache.set('someKey', 'someValue');
console.log(cache.get('someKey')); // Logs 'someValue'
cache.remove('someKey');
console.log(cache.get('someKey')); // Logs null

Creation

SimpleCache([options])

• Arguments:
  • { Object } [options]
    • { number } ttl
    • { string } namespace
    • { boolean } debug
• Returns: SimpleCache Instance

ttl

• Type: number
• Default: 1000 * 60 * 60 * 24 | (24 Hours)
• Details: Defines the global default for caching time in milliseconds, can be overridden per item. See overriding ttl for more info.

namespace

• Type: string
• Default: SC_
• Details: Defines the global namespace prefix for all cached items.

debug

• Type: boolean
• Default: false
• Details: Enables verbose logging for all operations. See debugging for more info.

Example:

const cache = new SimpleCache({
  ttl: 1000 * 30, // 30 seconds
  namespace: 'MYAPP_',
  debug: true,
});

Docs

cache.set(key, value, [session])

• Arguments:
  • { string } key
  • { string | Object } value
  • { boolean } [session]
• Description:

cache.set is used to store values in either local or session storage. The default storage location is local storage. To indicate session storage as the desired data store just pass true for the session parameter. Values provided can be anything serializable via JSON.stringify, this includes strings, booleans, Objects, etc.

NOTE: All operations provided by SimpleCache can be called in bulk, see bulk operations for more info.

• Example:

  cache.set('myString', 'myValue');
  cache.set('myObject', { isCool: true });
  cache.set('myBool', true);

cache.get(key)

• Arguments:
  • { string } key
• Returns:
  • { string | boolean | Object } value
• Description:

cache.get provides a uniform way to retrieve any value that has been stored by SimpleCache. The values are stringified so they will be accessible as JavaScript objects after you retrieve them. cache.get also provides waterfall logic for retrieval. Meaning session storage is checked first followed by local storage if nothing is found. Since session storage is more fragile it is respected as the highest priority for cached items.

NOTE: All operations provided by SimpleCache can be called in bulk, see bulk operations for more info.

• Example:

  const myString = cache.get('myString');
  console.log(myString); // Prints 'myValue'

  const myObject = cache.get('myObject');
  console.log(myObject.isCool); // Prints true

  const myBool = cache.get('myBool');
  if (myBool) {
    console.log(myBool); // Prints true
  }

cache.remove(key)

• Arguments:
  • { string } key
• Description:

cache.remove will remove a cached value from both session storage and local storage.

NOTE: All operations provided by SimpleCache can be called in bulk, see bulk operations for more info.

• Example:

  cache.remove('myString');

  console.log(cache.get('myString')); // Prints null

Bulk Operations

cache.set, cache.get and cache.remove have all been written to support bulk operations in addition to single input. This is accomplished by passing an array of values rather than a single input. It's worth noting that all bulk operations will return a promise that you can chain or await.

cache.set(values, [session])

• Arguments:
  • { Array<Object> } values
    • { string } key
    • { string | boolean | Object } value
  • { boolean } [session]
• Description:

cache.set requires an array of objects that contain the two properties key and value. The properties are fairly self-explanatory. Key is the string value to be used as the key and value will be the serializable value to be stored with the associated key.

• Example:

  await cache.set([
    { key: 'myString1', value: 'value1' },
    { key: 'myString2', value: 'value2' },
    { key: 'myString3', value: 'value3' },
  ]);

  console.log(cache.get('myString2')); // Prints 'value2'

cache.get(keys)

• Arguments:
  • { Array<string> } keys
• Returns:
  • { Array<any> } values
• Description:

cache.get requires an array of strings that correlate to keys being requested. The bulk operations follow the same waterfall logic that the singular operation does.

• Example:

  await cache.set([
    { key: 'myString1', value: 'value1' },
    { key: 'myString2', value: 'value2' },
    { key: 'myString3', value: 'value3' },
  ]);

  const values = await cache.get(['myString1', 'myString5', 'myString3']);
  console.log(values)
  // Prints ['value1', null, 'value3']

cache.remove(keys)

• Arguments:
  • { Array<string> } keys
• Description:

cache.remove requires an array of strings that correlate to keys being requested. It will then remove that cached value from both session storage and local storage.

• Example:

  await cache.set([
    { key: 'myString1', value: 'value1' },
    { key: 'myString2', value: 'value2' },
    { key: 'myString3', value: 'value3' },
  ]);

  await cache.remove(['myString1', 'myString2', 'myString3']);

  const values = await cache.get(['myString1', 'myString2', 'myString3']);
  console.log(values)
  // Prints [null, null, null]

Overriding TTL

Short for Time To Live, ttl specifies how long to respect a cached value before determining it has expired. While SimpleCache gives you the global ttl as a default for all items being cached, it also gives you the ability to specify a ttl on a per item basis. However, this only works if you pass an Object into set that has a ttl property. Currently you have to pass single item array if you want to set custom ttl for only one item.

Example:

  const myObject = {
    value: 'Some string goes here!',
    ttl: 5000, // 5 Seconds
  };
  cache.set('myKey', myObject);

  // After 2 Seconds the value will still be available
  setTimeout(() => {
    console.log(cache.get('myKey')) // Prints { value: 'Some string goes here!' }
  }, 2000);

  // 
  setTimeout(() => {
    console.log(cache.get('myKey')) // Prints null
  }, 6000);

Waterfall

When retrieving values SimpleCache uses waterfall logic when attempting to find stored values. Meaning session storage is checked first, followed by local storage if nothing is found. Since session storage is more fragile it is respected as the highest priority for cached items.

Debugging

SimpleCache has very verbose logging if you need to figure out why something isn't working the way you'd expect. Just pass debug: true to enable this. SimpleCache uses either the default namespace, or the one you provided to prefix all log messages.

Example:

import SimpleCache from '@stetsonpierce/simple-cache';

const cache = new SimpleCache({
  debug: true,
});

cache.set('myKey', 'myValue');

# Example Output
15:18:03.550 SimpleCache:Storing in Local
15:18:03.550 SimpleCache:Setting ttl: 1534577434218
15:18:03.550 SimpleCache:Set Single
15:18:03.551 SimpleCache:"SimpleCache:test":{"value":true,"ttl":1534577434218}

Changelog

v3.0

Major Changes:

• Fixed bug where setting bulk values wouldn't save in session storage
• logMessages prop renamed to debug
• All single actions are now synchronous so you don’t have to await them
• All operations now return some value

Minor Changes:

• Added tests with 100% coverage
• Refactored app to make it more maintainable, testable and approachable