Skip to content

RunCache is a dependency-free, lightweight runtime caching library for JavaScript and TypeScript.

License

Notifications You must be signed in to change notification settings

helloscoopa/run-cache

Folders and files

NameName
Last commit message
Last commit date

Latest commit

06edb6b · Sep 29, 2024

History

14 Commits
Sep 19, 2024
Sep 19, 2024
Sep 29, 2024
Sep 14, 2024
Sep 14, 2024
Sep 15, 2024
Sep 29, 2024
Sep 13, 2024
Sep 19, 2024
Sep 29, 2024
Sep 13, 2024

Repository files navigation

npm-version license ci-build ci-tests

RuntimeCache

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",
});