cacheism

Simple caching library

Overview

The goal of cacheism is to wrap an async function with caching logic where we can easily specify under what circumstances we want to return the cache or fetch the live data.

Your callback will get passed to it a Hit if there is an existing cache stored or a Miss if there is no existing cache.

const Cacheism = require('@andrewshell/cacheism');

const datadir = __dirname + '/data';
const cache = new Cacheism(Cacheism.store.filesystem({ datadir }));

async function run() {
    let result = await cache.go('-internal', 'hoopla', Cacheism.Status.cacheOnFail, async (existing) => {
        if (Math.random() < 0.5) {
            throw Error('Death');
        }
        return { message: 'Hoopla!' };
    });

    if (result.isHit) {
        console.dir(result.data);
    }

    if (result.error) {
        console.error(result.error);
    }
}

run().catch(err => console.error(err));

Statuses

Only Fresh

The onlyFresh status is for times where we never want to use the cache, but we want to fetch the fresh data and store it in the cache for other requests.

Cache on Fail

The cacheOnFail status is for times where we want to try to fetch fresh data, but if an error is thrown, use the cache if present.

Prefer Cache

The preferCache status is for times where we want to use the cache if available and only fetch fresh if the cache is not available.

Only Cache

The onlyCache status if for times where we don't want to attempt to fetch fresh data and only return the cache if present.

Results

The cache.go function will always return either a Hit or a Miss object.

Hit

A hit is returned when we have good data. The cached param will be true if the data was fetched from cache versus fresh data.

Hit {
  version: 3,
  cacheName: '-internal/hoopla',
  cached: true,
  created: 2023-04-02T22:00:49.320Z,
  data: { message: 'Hoopla!' },
  error: Error: Death
      at /Users/andrewshell/code/test-cacheism/index.js:9:19
      at Cacheism.go (/Users/andrewshell/code/cacheism/lib/cacheism.js:30:30)
      at async run (/Users/andrewshell/code/test-cacheism/index.js:7:18),
  errorTime: 2023-04-02T22:00:49.928Z,
  consecutiveErrors: 1,
  etag: '"15-QcHvuZdyxCmLJ4zoYIPsP6pkNoM"',
  isHit: true,
  isMiss: false
}

In the case of Cache on Fail, the error param may be set which is the error thrown while fetching fresh data.

Miss

A miss is returned when we don't have good data. For instance, if there wasn't cached data and an error was thrown while fetching fresh data. You'll also get a miss if you fetch with the onlyCache status and there isn't a cache.

Miss {
  version: 3,
  cacheName: '-internal/hoopla',
  cached: false,
  created: 2023-04-02T22:02:30.294Z,
  data: null,
  error: Error: Missing cache
      at Cacheism.go (/Users/andrewshell/code/cacheism/lib/cacheism.js:28:19)
      at async run (/Users/andrewshell/code/test-cacheism/index.js:7:18),
  errorTime: 2023-04-02T22:02:30.294Z,
  consecutiveErrors: 1,
  etag: null,
  isHit: false,
  isMiss: true
}