@surjit/cache

A tiny yet elegant in-memory-cache implementation in javascript.

Install: npm i @surjit/cache

API

Get Started

import Cache from '@surjit/cache';

const cache = new Cache();

// store in cache
cache.put('foo', 'bar'); // returns "bar"
// set cache validity in milliseconds
cache.put('foo', 'bar', 5000); // returns "bar"

// get cached data
cache.get('foo'); // returns "bar"

// delete cached data
cache.del('foo'); // returns true

cache.put(key: any, value: any | unknown, timeout: number, onTimeoutCallback: (key: string, value: any) => any): any

Returns the cached data.

| Param | Data Type | Description | Required | | ----------------- | ---------------------------------- | ---------------------------------------------------------------------- | -------- | | key | any | Cache key | YES | | value | any \| unknown | Data to be cached | YES | | timeout | number \| undefined | Cache validity in milliseconds. Leave undefined for infinite validity. | NO | | onTimeoutCallback | (key: string, value: any) => any | Function to be called when the cache expires | NO |

cache_key can be of any data-type. Make sure to pass the correct reference to the key for fetching the cached data if you're using a referenced data-type for cache_keys.

Some examples of supported keys:

• null
• undefined
• NaN
• true
• false
• 0
• 1
• Number.POSITIVE_INFINITY
• Number.NEGATIVE_INFINITY
• ''
• 'a'
• []
• {}
• [1, 'a', false]
• { a: 1, b: 'a', c: false }
• function key() {}
• () => {}

cache.put(null, 'value-x'); // valid ✅
cache.put(undefined, 'value-x'); // valid ✅
cache.put(NaN, 'value-x'); // valid ✅
cache.put(true, 'value-x'); // valid ✅
cache.put(false, 'value-x'); // valid ✅
cache.put(0, 'value-x'); // valid ✅
cache.put(1, 'value-x'); // valid ✅
cache.put(Number.POSITIVE_INFINITY, 'value-x'); // valid ✅
cache.put(Number.NEGATIVE_INFINITY, 'value-x'); // valid ✅
cache.put('', 'value-x'); // valid ✅
cache.put('a', 'value-x'); // valid ✅
cache.put([], 'value-x'); // valid ✅
cache.put({}, 'value-x'); // valid ✅
cache.put([1, 'a', false], 'value-x'); // valid ✅
cache.put({ a: 1, b: 'a', c: false }, 'value-x'); // valid ✅
cache.put(function key() {}, 'value-x'); // valid ✅
cache.put(() => {}, 'value-x'); // valid ✅

cache.get(key: any): any | null

Returns cached data or null if not-found or expired.

| Param | Data Type | Description | Required | | ----- | --------- | ----------- | -------- | | key | string | Cache key | YES |

cache.del(key: any): boolean

Returns true on deletion success and false on failure.

| Param | Data Type | Description | Required | | ----- | --------- | ----------- | -------- | | key | string | Cache key | YES |

cache.clear(): void

Clears the cache instance by deleting all cached data.

cache.memSize(): number

Returns the count of cache entries in the instance.

cache.keys(): string[]

Returns an array of keys of all the cached data in the instance.

cache.toJSON(options: { prettyIndentation: number }): string

Exports all the cached data (without the expiry information) to a JSON string, optionally prettifying the json with provided indentation.

cache.fromJSON(jsonToImport: string, options: { skipDuplicates: boolean }): number

Add bulk data to the cache.

cache.fromJSON(
  JSON.stringify({
    key1: {
      value: 'value1',
      expire: 'NaN', // infinite validity
    },
    key2: {
      value: 'value2',
      expire: Date.now() + 1000,
    },
  }),
);

Debug

There are some debugging features built-in to the library, such as keeping track of cache hits and misses, size of the cache, logging the cache interactions/operations.

Debugging features are turned off by default.

Enable Debugging

import Cache from '@surjit/cache';

const cacheV1 = new Cache({ debug: true });
// or
const cacheV2 = new Cache();
cacheV2.debug(true);

Once debugging is enabled, we get access to the following features

console.log(cache.hits); // count cache hits
console.log(cache.misses); // count of cache misses

Logging

By default javascript console is used as logger, and logs cache operations when debug mode is enabled.

const cacheV1 = new Cache({ debug: true, logger: CustomLogger });
// or
const cacheV2 = new Cache();
cacheV2.debug(true);
cacheV2.setLogger(CustomLogger);