Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CachedLookup: A Simple Package To Cache And Save On Expensive Lookups & Operations.

NPM version NPM downloads Language grade: JavaScript GitHub issues GitHub stars GitHub license


This package aims to simplify the task of implementing a short-lived caching system for an endpoint which may be calling another third party API under the hood with a usage/rate limit. This package can also help to alleviate pressure when consuming data from databases or I/O network operations by implementing a short lived cache that does not scale relative to incoming requests.


  • Simple-to-use API
  • Asynchronous By Nature
  • Customizable Cache Lifetime
  • Extremely Lightweight
  • No Dependencies


CachedLookup can be installed using node package manager (npm)

npm i cached-lookup

How To Use?

Below is a small snippet that shows how to use a CachedLookup instance.

const CachedLookup = require('cached-lookup');

// Create an instance that caches for 5 seconds
// This will ensure, new data is only fetched every 5 seconds
const CurrencyLookup = new CachedLookup(async () => {
    // Hit some third-party API to retrieve fresh currency data
    const result = await get_currency_values();
    // Perform some local parsing of the resolved data
    const parsed = parse_data(result);

    // Return parsed data for cached-lookup to cache and serve instantly for the next 5 seconds
    return parsed;

// Some webserver route utilizing the CachedLookup instance to serve currency data
webserver.get('/api/currency', async (request, response) => {
    // This will return the cached value for 5 seconds before retrieving a fresh value
    const data = await CurrencyLookup.cached(5000);
    return response.send(data);


Below is a breakdown of the CachedLookup class.

Constructor Parameters

  • new CachedLookup(Function: lookup): Creates a new CachedLookup instance.
    • lookup [Function]: Lookup handler which is invocated to get fresh results.
      • Note! this callback can be either synchronous or asynchronous.
      • Note! you must return/resolve a value through this callback for the caching to work properly.

CachedLookup Properties

Property Type Description
value Any Most recent cached value
updated_at Number Unix timestamp in milliseconds of latest update
in_flight Boolean Whether instance is currently looking up a fresh value

CachedLookup Methods

  • cached(Number: max_age): Consumes cached value with a fallback to fresh value if cached value has expired.
    • Returns a Promise which is then resolved to the lookup value.
    • Note parameter max_age should be a Number in milliseconds to specify the maximum acceptable cache age.
    • Note this method will reject when the lookup handler also rejects.
  • fresh(): Retrieves fresh value from the lookup handler.
    • Returns a Promise which is then resolved to the lookup value.
  • expire(): Expires current cached value marking instance to fetch fresh value on next cached() invocation.




A Simple Package To Cache And Save On Expensive Lookups & Operations.




No packages published