npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

cached-lookup

v5.4.0

Published

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

Downloads

2,212

Readme

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

NPM version NPM downloads GitHub issues GitHub stars GitHub license

Motivation

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.

Features

  • Simple-to-use API
  • TypeScript Support
  • Dynamic Cache Consumption
  • CPU & Memory Efficient
  • No Dependencies

Installation

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 a cached lookup instance which fetches music concerts from different cities on a specific date
const ConcertsLookup = new CachedLookup(async (country, state, city) => {
    // Assume that the function get_city_concerts() is calling a Third-Party API which has a rate limit
    const concerts = await get_city_concerts(country, state, city);

    // Simply return the data and CachedLookup will handle the rest
    return concerts;
});

// Create some route which serves this data with a 10 second intermittent cache
webserver.get('/api/concerts/:country/:state/:city', async (request, response) => {
    // Retrieve the city value from the request - assume there is user validation done on this here
    const { country, state, city } = request.path_parameters;

    // Retrieve data from the CachedLookup with the cached() and pass the city in the call to the lookup handler
    // Be sure to specify the first parameter as the max_age of the cached value in milliseconds
    // In our case, 10 seconds would be 10,000 milliseconds
    const concerts = await ConcertsLookup.cached(1000 * 10, country, state, city);

    // Simply return the data to the user
    // Because we retrieved this data from the ConcertsLookup with the cached() method
    // We can safely assume that we will only perform up to 1 Third-Party API request per city every 10 seconds
    return response.json({
        concerts
    });
});

CachedLookup

Below is a breakdown of the CachedLookup class.

Constructor Parameters

  • new CachedLookup(Function: lookup): Creates a new CachedLookup instance with default options.
  • new CachedLookup(Object?: options, Function(...arguments): lookup): Creates a new CachedLookup instance with custom options.
    • options [Object]: Constructor options for this instance.
      • auto_purge [Boolean]: Whether to automatically purge cache values when they have aged past their last known maximum age.
        • Default: true
      • purge_age_factor [Number]: The factor by which to multiply the last known maximum age of a cache value to determine the age at which it should be purged.
        • Default: 1.5
    • lookup [Function]: Lookup handler which is called to get fresh values.
      • 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.
      • Note! arguments passed to the methods below will be available in each call to this lookup handler.

CachedLookup Properties

| Property | Type | Description | | :-------- | :------- | :------------------------- | | lookup | function(...arguments) | Lookup handler of this instance. | | cache | Map<string, ValueRecord> | Internal map of cached values. | | promises | Map<string, Promise<T>> | Internal map of promises for pending lookups. |

CachedLookup Methods

  • cached(Number: max_age, ...arguments): Returns the cached value for the provided set of arguments from the lookup handler. Automatically falls back to a fresh() value if no cached value within the max_age is available.
    • Returns a Promise which is resolved to the cached value with a fall back to the fresh value.
    • Note the parameter max_age should be a Number in milliseconds to specify the maximum acceptable cache age.
    • Note this method will automatically fall back to a fresh() call if no viable cache value is available.
    • Note the returned Promise will reject when the lookup handler also rejects.
    • Note the provided arguments after the max_age will be available inside of the lookup handler function.
    • Note this method should be used over rolling() if you want to ensure cache freshness within the max_age threshold at the sacrifice of increased latency whenever a fresh() is resolved to satify the max_age requirement.
  • rolling(Number: target_age, ...arguments): Returns the cached value for the provided set of arguments from the lookup handler. Instantly resolves the most recently cached value while triggering a fresh() value call in the background to reload the cache on a rolling basis according to the target_age.
    • Note this method has the same signature as the cached() method above.
    • Note this method should be used over cached() if you want to maintain low latency at the sacrifice of guaranteed cache freshness.
  • fresh(...arguments): Retrieves the fresh value for the provided set of arguments from the lookup handler.
    • Returns a Promise which is resolved to the fresh value.
  • get(...arguments): Returns the cached value for the provided set of arguments if one exists in cache.
    • Returns the cached value or undefined.
  • expire(...arguments): Expires the cached value for the provided set of arguments.
    • Returns a Boolean which specifies whether a cached value was expired or not.
  • in_flight(...arguments): Checks whether a fresh value is currently being resolved for the provided set of arguments.
    • Returns a Boolean to specify the result.
  • updated_at(...arguments): Returns the last value update timestamp in milliseconds for the provided set of arguments.
    • Returns a Number or undefined if no cached value exists.
  • clear(): Clears all the cached values and resets the internal cache state.
  • Note the ...arguments are optional but must be of the following types: Boolean, Number, String or an Array of these types.

CachedLookup Events

  • [fresh]: The fresh event is emitted whenever a fresh value is retrieved from the lookup function with a given set of arguments.
    • Example: CachedLookup.on('fresh', (value, arg1, arg2, arg3) => { /* Your Code */ });
  • [purge]: The purge event is emitted whenever a stale cache value is purged from the cache.
    • Example: CachedLookup.on('purge', (value, arg1, arg2, arg3) => { /* Your Code */ });

ValueRecord Properties

| Property | Type | Description | | :-------- | :------- | :------------------------- | | value | T (Generic) | The cached value. | | max_age | undefined | Number | The smallest known max_age of value. | | updated_at | Number | Timestamp (In milliseconds) of when this value was cached. |

License

MIT