@epic-web/cachified

The cachified function is the primary entry point. It manages the lifecycle of a cached value by checking the cache, potentially fetching a fresh value via getFreshValue, and updating the cache.

To use it, you must provide a key, a cache implementation conforming to the Cache interface, and a getFreshValue function. You can also specify a ttl (Time To Live) in milliseconds.

import { cachified, Cache, totalTtl } from '@epic-web/cachified';

// A simple Cache implementation example
const lru: Cache = {
  set(key, value) { /* implementation */ },
  get(key) { /* implementation */ },
  delete(key) { /* implementation */ },
};

async function getUserById(userId: number) {
  return cachified({
    key: `user-${userId}`,
    cache: lru,
    async getFreshValue() {
      const response = await fetch(`https://jsonplaceholder.typicode.com/users/${userId}`);
      return response.json();
    },
    ttl: 300_000, // 5 minutes
  });
}

Use the forceFresh option to bypass the cache and trigger getFreshValue immediately. If the attempt to fetch a fresh value fails, you can use fallbackToCache to return a cached value instead. fallbackToCache accepts a duration in milliseconds; if the cached value is older than this duration, it will not be used as a fallback. The default is Infinity.

import { cachified } from '@epic-web/cachified';

const cache = new Map();

function getUserById(userId: number, forceFresh?: boolean) {
  return cachified({
    forceFresh,
    /* when getting a forced fresh value fails we fall back to cached value
       as long as it's not older then 5 minutes */
    fallbackToCache: 300_000 /* 5 minutes, defaults to Infinity */,

    cache,
    key: `user-${userId}`,
    async getFreshValue() {
      const response = await fetch(
        `https://jsonplaceholder.typicode.com/users/${userId}`,
      );
      return response.json();
    },
  });
}

Instead of deleting a key (hard purge), use softPurge to mark an entry as stale. This sets the ttl to 0 but keeps the staleWhileRevalidate window active. The next request will return the outdated data immediately but trigger a background refresh, preventing a sudden surge of requests to your data source.

import { cachified, softPurge } from '@epic-web/cachified';

const cache = new Map();

function getUserById(userId: number) {
  return cachified({
    cache,
    key: `user-${userId}`,
    ttl: 300_000,
    async getFreshValue() {
      const response = await fetch(
        `https://jsonplaceholder.typicode.com/users/${userId}`,
      );
      return response.json();
    },
  });
}

console.log(await getUserById(1));

await softPurge({
  cache,
  key: 'user-1',
});

// You can also manually overwrite the SWR window during soft purge
await softPurge({
  cache,
  key: 'user-1',
  staleWhileRevalidate: 60_000,
});

If your data format changes, you can use the migrate function inside checkValue to transform old cached values into the new format. If migrate is called, the new value is returned immediately and the cache is updated with the migrated version without calling getFreshValue.

import { cachified, createCacheEntry } from '@epic-web/cachified';

const cache = new Map();

/* Let's assume we've previously only stored emails not user objects */
cache.set('user-1', createCacheEntry('someone@example.org'));

function getUserById(userId: number) {
  return cachified({
    checkValue(value, migrate) {
      if (typeof value === 'string') {
        return migrate({ email: value });
      }
    },

    key: 'user-1',
    cache,
    getFreshValue() {
      throw new Error('This is never called');
    },
  });
}

console.log(await getUserById(1));
// > logs { email: 'someone@example.org' }

Since cache contents can be modified by other processes or become outdated due to code changes, use the checkValue function to ensure data integrity. checkValue is called with the value retrieved from the cache (and also with the value returned by getFreshValue).

To invalidate a bad value and trigger a refresh, checkValue can:

• Throw an Error.
• Return a string (the reason/message).
• Return false.
• Return undefined, true, or null to indicate the value is valid.

import { cachified, createCacheEntry } from '@epic-web/cachified';

const cache = new Map();

/* Assume something bad happened and we have an invalid cache entry... */
cache.set('user-1', createCacheEntry('INVALID') as any);

function getUserById(userId: number) {
  return cachified({
    checkValue(value: unknown) {
      if (!isRecord(value)) {
        throw new Error(`Expected user to be object, got ${typeof value}`);
      }

      if (typeof value.email !== 'string') {
        return `Expected user-${userId} to have an email`;
      }

      if (typeof value.username !== 'string') {
        return false;
      }
    },

    cache,
    key: `user-${userId}`,
    async getFreshValue() {
      const response = await fetch(
        `https://jsonplaceholder.typicode.com/users/${userId}`,
      );
      return response.json();
    },
  });
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}