TypeScript icon, indicating that this package has built-in type declarations

    3.0.2 • Public • Published

    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
    • TypeScript Support
    • Asynchronous By Nature
    • Customizable Cache Lifetime
    • Dynamic Cache Consumption
    • 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.




    npm i cached-lookup

    DownloadsWeekly Downloads






    Unpacked Size

    11 kB

    Total Files


    Last publish


    • kartikk221