pure-cache

Cache with confidence 🎉

Ultra fast & tiny(around 1.28kb gzipped) in-memory JavaScript cache with near realtime cache expiry feature ⚡

Works in any JavaScript runtime(node or browser) ✨

Table of Contents

• Install
• Basic Usage
• Events
• API
• Contribute
• Credits
• License

Install

NPM

npm install pure-cache

Yarn

yarn add pure-cache

UMD build

<script src="https://unpkg.com/pure-cache/dist/pure-cache.umd.js"></script>

Basic usage

• Import library

  import PureCache from 'pure-cache';
  // or const PureCache = require('pure-cache');

• Create cacheStore instance

  // Create instance of cache store and set cache expiry timeout to 500ms
  const cacheStore = new PureCache({ expiryCheckInterval: 500 });

• Setup expiry handler

  // Setup a expiry listener, this will be called when data expires
  const onExpiry = ({ key, data: { value, expiryAt } }) => {
      // Do something with expired key
      console.log(`Key:${key} with value:${value} expired at ${expiryAt}.`);
  };
  cacheStore.on('expiry', onExpiry);

• Put/Get data from cacheStore

  // Put 'bar' data into 'foo' key in cache and configure it to expire after 30s
  cacheStore.put('foo', 'bar', 30000);
  
  // Get 'foo' key value from cache
  cacheStore.get('foo'); // { value: 'bar', addedAt: 1527052395294, expiryAt: 1527052425294 }

• Wait for expiry

  // Wait till expiry time(basically 30+ seconds in this case)
  const wait = t => new Promise(r => setTimeout(r, t));
  await wait(31000);
  
  // Now the cache will return null value for 'foo' key
  cacheStore.get('foo'); // null

• Cleanup listeners

  // remove listeners after you are done
  cacheStore.off('expiry', onExpiry);
  
  // IMPORTANT! When done, make sure you cleanup the instance
  cacheStore.dispose();

Checkout API for advanced usage.

Events

Events are triggered when operations like add, get, remove, clear are performed on cacheStore or when the cache expires.

• expiry

  cacheStore.on('expiry', ({ key, data: { value, addedAt, expiryAt } }) => {
      // ...
  });

• add

  cacheStore.on('add', ({ key, data: { value, addedAt, expiryAt } }) => {
      // ...
  });

• get

  cacheStore.on('get', ({ key, data: { value, addedAt, expiryAt } }) => {
      // ...
  });

• remove

  cacheStore.on('remove', ({ key, data: { value, addedAt, expiryAt } }) => {
      // ...
  });

• clear

  cacheStore.on('clear', () => {
      // ...
  });

API

• Pure Cache
• In Memory Expirer (Internal)

Contribute

Thanks for taking time to contribute, please read docs and checkout src to understand how things work.

Reporting Issues

Found a problem? Want a new feature? First of all see if your issue or idea has already been reported. If don't, just open a new clear and descriptive issue.

Submitting pull requests

Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.

• Fork it!
• Clone your fork: git clone https://github.com/<your-username>/pure-cache
• Navigate to the newly cloned directory: cd pure-cache
• Create a new branch for the new feature: git checkout -b my-new-feature
• Install the tools necessary for development: yarn
• Make your changes.
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request with full remarks documenting your changes

Credits

• developit/mitt for awesome library and readme template 🙏

License

MIT License © Ganapati V S