Run~time~Cache

RunCache is a dependency-free, lightweight runtime caching library for JavaScript and TypeScript that allows you to cache string values with optional time-to-live (TTL) settings. It also supports caching values generated from sync/async functions and provide methods to refetch them on expiry or on demand; with a set of events to keep track of the state of the cache.

Features

• Dependency-free: Does not consume any external dependencies.
• In-memory caching: A runtime cache that gives you quick access.
• Sync/async source functions: Fetch dynamic data from user-defined functions.
• Events: Get to know when cache expires, refetched or refetch fails.
• Intuitive SDK: Clean interface to access data.

Installation

To use RunCache, simply install it via npm:

npm install run-cache

Usage

Import library

import { RunCache } from "run-cache";

Set cache

// Set a cache value
await RunCache.set({
  key: "Key",
  value: "Value",
});

// Set a cache value with 60s ttl
await RunCache.set({
  key: "Key",
  value: "Value",
  ttl: 60000 // in milliseconds
});

// Set a cache value with function to fetch the value later
await RunCache.set({
  key: "Key",
  sourceFn: () => { return Promise.resolve("Value") }
});

/*
  Additionally, set autoRefetch: true along with a ttl value
  to enable automatic refetching. This will cause the cache
  to refetch the value upon expiry whenever the consumer
  calls `get` on the specified key.
*/
await RunCache.set({
  key: "Key",
  sourceFn: () => { return Promise.resolve("Value") }
  autoRefetch: true,
  ttl: 10000,
});

/*
  Use a callback function to get to know when your cache expires
  or when its being refetched. The expiry is triggered only
  on demand, not automatically.
*/
import { EventParam } from "run-cache";

// Event of all expiries
RunCache.onExpiry((cache: EventParam) => {
  console.log(`Cache of key '${cache.key}' has been expired`);
})

// Event of a specific key expiry
RunCache.onKeyExpiry('Key', (cache: EventParam) => {
  console.log(`Specific key has been expired`);
})

await RunCache.set({
  key: "Key",
  ttl: 10000
})

// Event of any key refetches
RunCache.onRefetch((cache: EventParam) => {
  console.log(`Cache of key '${cache.key}' has been refetched`);
})

// Event of a specific key refetch
RunCache.onKeyRefetch('Key', (cache: EventParam) => {
  console.log(`Specific key has been refetched`);
})

// Event of a key refetch failure
RunCache.onRefetchFailure((cache: EventParam) => {
  console.log(`Cache of key '${cache.key}' has been refetched`);
})

// Event of a specific key refetch failure
RunCache.onKeyRefetchFailure('Key', (cache: EventParam) => {
  console.log(`Specific key has been failed to refetch`);
})

await RunCache.set({
  key: "Key",
  ttl: 10000,
  sourceFn: () => { return Promise.resolve("Value") }
})

Refetch cache

// Refetch the cache value (Only works if the key is set with a sourceFn)
await RunCache.refetch("Key");

Get cache

/* 
  Get a value for a given cache key, will refetch value automatically
  if `sourceFn` is provided and `autoRefetch: true` 
*/
const value = await RunCache.get("Key");

Delete cache

// Delete a specific cache key
RunCache.delete("Key");

// Delete all cache keys
RunCache.flush();

Check the existence of a specific cache

// Returns a boolean, expired cache returns `false` even if they're refetchable
const hasCache = RunCache.has("Key");

Clear event listeners

// Clear all listeners
RunCache.clearEventListeners();

// Clear specific event listeners
RunCache.clearEventListeners({
  event: "expiry",
});

// Clear specific event key listeners
RunCache.clearEventListeners({
  event: "expiry",
  key: "Key",
});