neat wrapper for various caches
npm install @epic-web/cachified
Cachified allows you to cache values with support for time-to-live (ttl),
stale-while-revalidate (swr), cache value validation, batching, and
type-safety.
``
npm install @epic-web/cachified
[![Build Status][build-badge]][build]
[![MIT License][license-badge]][license]
[![Code of Conduct][coc-badge]][coc]
Watch the talk "Caching for Cash 🤑"
on EpicWeb.dev:
`sh`
npm install @epic-web/cachifiedyarn add @epic-web/cachified
`ts
import { LRUCache } from 'lru-cache';
import { cachified, CacheEntry, Cache, totalTtl } from '@epic-web/cachified';
/ lru cache is not part of this package but a simple non-persistent cache /
const lruInstance = new LRUCache
const lru: Cache = {
set(key, value) {
const ttl = totalTtl(value?.metadata);
return lruInstance.set(key, value, {
ttl: ttl === Infinity ? undefined : ttl,
start: value?.metadata?.createdTime,
});
},
get(key) {
return lruInstance.get(key);
},
delete(key) {
return lruInstance.delete(key);
},
};
function getUserById(userId: number) {
return cachified({
key: user-${userId},checkValue
cache: lru,
async getFreshValue() {
/* Normally we want to either use a type-safe API or butany
to keep this example simple we work with */https://jsonplaceholder.typicode.com/users/${userId}
const response = await fetch(
,
);
return response.json();
},
/* 5 minutes until cache gets invalid
Optional, defaults to Infinity /
ttl: 300_000,
});
}
// Let's get through some calls of getUserById:
console.log(await getUserById(1));
// > logs the user with ID 1
// Cache was empty, getFreshValue got invoked and fetched the user-data that
// is now cached for 5 minutes
// 2 minutes later
console.log(await getUserById(1));
// > logs the exact same user-data
// Cache was filled an valid. getFreshValue was not invoked
// 10 minutes later
console.log(await getUserById(1));
// > logs the user with ID 1 that might have updated fields
// Cache timed out, getFreshValue got invoked to fetch a fresh copy of the user`
// that now replaces current cache entry and is cached for 5 minutes
`tsInfinity
interface CachifiedOptions
/**
* Required
*
* The key this value is cached by
* Must be unique for each value
*/
key: string;
/**
* Required
*
* Cache implementation to use
*
* Must conform with signature
* - set(key: string, value: object): void | Promise
* - get(key: string): object | Promise
*/
ttl?: number;
/**
* Amount of milliseconds that a value with exceeded ttl is still returned
* while a fresh value is refreshed in the background
*
* Should be positive, can be infinite
*
* Default:
*/
staleWhileRevalidate?: number;
/**
* Alias for staleWhileRevalidate
*/
swr?: number;
/**
* Validator that checks every cached and fresh value to ensure type safety
*
* Can be a standard schema validator or a custom validator function
* @see https://github.com/standard-schema/standard-schema?tab=readme-ov-file#what-schema-libraries-implement-the-spec
*
* Value considered ok when:
* - schema succeeds
* - validator returns
* - true
* - migrate(newValue)
* - undefined
* - null
*
* Value considered bad when:
* - schema throws
* - validator:
* - returns false
* - returns reason as string
* - throws
*
* A validator function receives two arguments:
* 1. the value
* 2. a migrate callback, see https://github.com/epicweb-dev/cachified#migrating-values
*
* Default: - no validationfalse
*/
checkValue?:
| CheckValue
| StandardSchemaV1
| Schema
/**
* Set true to not even try reading the currently cached value
*
* Will write new value to cache even when cached value is
* still valid.
*
* Default:
*/
forceFresh?: boolean;
/**
* Whether or not to fall back to cache when getting a forced fresh value
* fails
*
* Can also be a positive number as the maximum age in milliseconds that a
* fallback value might have
*
* Default:
*/
fallbackToCache?: boolean | number;
/**
* Promises passed to represent background tasks which must beundefined
* completed before the server can shutdown. e.g. swr cache revalidation
*
* Useful for serverless environments such as Cloudflare Workers.
*
* Default:
*/
waitUntil?: (promise: Promise
/**
* Trace ID for debugging, is stored along cache metadata and can be accessed
* in and reporter`
*/
traceId?: any;
}
There are some adapters available for common caches. Using them makes sure the used caches cleanup outdated values themselves.
- Adapter for redis : cachified-redis-adapter
- Adapter for redis-json : cachified-redis-json-adapter
- Adapter for Cloudflare KV : cachified-adapter-cloudflare-kv repository
- Adapter for SQLite : cachified-adapter-sqlite
Specify a time window in which a cached value is returned even though
it's ttl is exceeded while the cache is updated in the background for the next
call.
`ts
import { cachified } from '@epic-web/cachified';
const cache = new Map();
function getUserById(userId: number) {
return cachified({
ttl: 120_000 / Two minutes /,
staleWhileRevalidate: 300_000 / Five minutes /,
cache,
key: user-${userId},https://jsonplaceholder.typicode.com/users/${userId}
async getFreshValue() {
const response = await fetch(
,
);
return response.json();
},
});
}
console.log(await getUserById(1));
// > logs the user with ID 1
// Cache is empty, getFreshValue gets invoked and and its value returned and
// cached for 7 minutes total. After 2 minutes the cache will start refreshing in background
// 30 seconds later
console.log(await getUserById(1));
// > logs the exact same user-data
// Cache is filled an valid. getFreshValue is not invoked, cached value is returned
// 4 minutes later
console.log(await getUserById(1));
// > logs the exact same user-data
// Cache timed out but stale while revalidate is not exceeded.
// cached value is returned immediately, getFreshValue gets invoked in the
// background and its value is cached for the next 7 minutes
// 30 seconds later
console.log(await getUserById(1));
// > logs fresh user-data from the previous call
// Cache is filled an valid. getFreshValue is not invoked, cached value is returned`
We can use forceFresh to get a fresh value regardless of the values ttl or stale while validate
`ts
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},https://jsonplaceholder.typicode.com/users/${userId}
async getFreshValue() {
const response = await fetch(
,
);
return response.json();
},
});
}
console.log(await getUserById(1));
// > logs the user with ID 1
// Cache is empty, getFreshValue gets invoked and and its value returned
console.log(await getUserById(1, true));
// > logs fresh user with ID 1
// Cache is filled an valid. but we forced a fresh value, so getFreshValue is invoked`
In practice we can not be entirely sure that values from cache are of the types we assume.
For example other parties could also write to the cache or code is changed while cache
stays the same.
`ts
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)) {
/ We can either throw to indicate a bad value /
throw new Error(Expected user to be object, got ${typeof value});
}
if (typeof value.email !== 'string') {
/ Or return a reason/message string /
return Expected user-${userId} to have an email;
}
if (typeof value.username !== 'string') {
/ Or just say no... /
return false;
}
/ undefined, true or null are considered OK /
},
cache,
key: user-${userId},https://jsonplaceholder.typicode.com/users/${userId}
async getFreshValue() {
const response = await fetch(
,
);
return response.json();
},
});
}
function isRecord(value: unknown): value is Record
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
console.log(await getUserById(1));
// > logs the user with ID 1
// Cache was not empty but value was invalid, getFreshValue got invoked and
// and the cache was updated
console.log(await getUserById(1));
// > logs the exact same data as above
// Cache was filled an valid. getFreshValue was not invoked`
> ℹ️ checkValue is also invoked with the return value of getFreshValue
We can also use zod, valibot or other libraries implementing the standard schema spec to ensure correct types
`ts
import { cachified, createCacheEntry } from '@epic-web/cachified';
import z from 'zod';
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: z.object({
email: z.string(),
}),
cache,
key: user-${userId},https://jsonplaceholder.typicode.com/users/${userId}
async getFreshValue() {
const response = await fetch(
,
);
return response.json();
},
});
}
console.log(await getUserById(1));
// > logs the user with ID 1
// Cache was not empty but value was invalid, getFreshValue got invoked and
// and the cache was updated
console.log(await getUserById(1));
// > logs the exact same data as above
// Cache was filled an valid. getFreshValue was not invoked`
We can create versions of cachified with defaults so that we don't have to
specify the same options every time.
`ts
import { configure } from '@epic-web/cachified';
import { LRUCache } from 'lru-cache';
/ lruCachified now has a default cache /
const lruCachified = configure({
cache: new LRUCache
});
const value = await lruCachified({
key: 'user-1',
getFreshValue: async () => 'ONE',
});
`
During normal app lifecycle there usually is no need for this but for
maintenance and testing these helpers might come handy.
`ts
import {
createCacheEntry,
assertCacheEntry,
isExpired,
cachified,
} from '@epic-web/cachified';
const cache = new Map();
/ Manually set an entry to cache /
cache.set(
'user-1',
createCacheEntry(
'someone@example.org',
/ Optional CacheMetadata /
{ ttl: 300_000, swr: Infinity },
),
);
/ Receive the value with cachified /
const value: string = await cachified({
cache,
key: 'user-1',
getFreshValue() {
throw new Error('This is not called since cache is set earlier');
},
});
console.log(value);
// > logs "someone@example.org"
/ Manually get a value from cache /
const entry: unknown = cache.get('user-1');
assertCacheEntry(entry); // will throw when entry is not a valid CacheEntry
console.log(entry.value);
// > logs "someone@example.org"
/ Manually check if an entry is expired /
const expired = isExpired(entry.metadata);
console.log(expired);
// > logs true, "stale" or false
/ Manually remove an entry from cache /
cache.delete('user-1');
`
When the format of cached values is changed during the apps lifetime they can
be migrated on read like this:
`ts
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 });
}
/ other validations... /
},
key: 'user-1',
cache,
getFreshValue() {
throw new Error('This is never called');
},
});
}
console.log(await getUserById(1));
// > logs { email: 'someone@example.org' }
// Cache is filled and invalid but value can be migrated from email to user-object
// getFreshValue is not invoked
console.log(await getUserById(1));
// > logs the exact same data as above
// Cache is filled an valid.
`
Soft-purging cached data has the benefit of not immediately putting pressure on the app
to update all cached values at once and instead allows to get them updated over time.
More details: Soft vs. hard purge
`ts
import { cachified, softPurge } from '@epic-web/cachified';
const cache = new Map();
function getUserById(userId: number) {
return cachified({
cache,
key: user-${userId},https://jsonplaceholder.typicode.com/users/${userId}
ttl: 300_000,
async getFreshValue() {
const response = await fetch(
,
);
return response.json();
},
});
}
console.log(await getUserById(1));
// > logs user with ID 1
// cache was empty, fresh value was requested and is cached for 5 minutes
await softPurge({
cache,
key: 'user-1',
});
// This internally sets the ttl to 0 and staleWhileRevalidate to 300_000
// 10 seconds later
console.log(await getUserById(1));
// > logs the outdated, soft-purged data
// cache has been soft-purged, the cached value got returned and a fresh value
// is requested in the background and again cached for 5 minutes
// 1 minute later
console.log(await getUserById(1));
// > logs the fresh data that got refreshed by the previous call
await softPurge({
cache,
key: 'user-1',
// manually overwrite how long the stale data should stay in cache
staleWhileRevalidate: 60_000 / one minute from now on /,
});
// 2 minutes later
console.log(await getUserById(1));
// > logs completely fresh data
`
> ℹ️ In case we need to fully purge the value, we delete the key directly from our cache
There are scenarios where we want to change the cache time based on the fresh
value (ref #25).
For example when an API might either provide our data or null and in case we
get an empty result we want to retry the API much faster.
`ts
import { cachified } from '@epic-web/cachified';
const cache = new Map();
const value: null | string = await cachified({
ttl: 60_000 / Default cache of one minute... /,
async getFreshValue(context) {
const response = await fetch(
https://jsonplaceholder.typicode.com/users/1,
);
const data = await response.json();
if (data === null) {
/ On an empty result, prevent caching /
context.metadata.ttl = -1;
}
return data;
},
cache,
key: 'user-1',
});
`
In case multiple values can be requested in a batch action, but it's not
clear which values are currently in cache we can use the createBatch helper
`ts
import { cachified, createBatch } from '@epic-web/cachified';
const cache = new Map();
async function getFreshValues(idsThatAreNotInCache: number[]) {
const res = await fetch(
https://example.org/api?ids=${idsThatAreNotInCache.join(',')},
);
const data = await res.json();
// Validate data here...
return data;
}
function getUsersWithId(ids: number[]) {
const batch = createBatch(getFreshValues);
return Promise.all(
ids.map((id) =>
cachified({
getFreshValue: batch.add(
id,
/* onValue callback is optional but can be used to manipulate
cache metadata based on the received value. (see section above) /
({ value, ...context }) => {},
),
cache,
key: entry-${id},
ttl: 60_000,
}),
),
);
}
console.log(await getUsersWithId([1, 2]));
// > logs user objects for ID 1 & ID 2
// Caches is completely empty. getFreshValues is invoked with [1, 2]
// and its return values cached separately
// 1 minute later
console.log(await getUsersWithId([2, 3]));
// > logs user objects for ID 2 & ID 3
// User with ID 2 is in cache, getFreshValues is invoked with [3]
// cachified returns with one value from cache and one fresh value
A reporter might be passed as second argument to cachified to log caching events, we ship a reporter
resembling the logging from Kents implementation
`ts
import { cachified, verboseReporter } from '@epic-web/cachified';
const cache = new Map();
await cachified(
{
cache,
key: 'user-1',
async getFreshValue() {
const response = await fetch(
https://jsonplaceholder.typicode.com/users/1,`
);
return response.json();
},
},
verboseReporter(),
);
please refer to the implementation of verboseReporter` when you want to implement a custom reporter.
MIT
[build-badge]: https://img.shields.io/github/actions/workflow/status/epicweb-dev/cachified/release.yml?branch=main&logo=github&style=flat-square
[build]: https://github.com/epicweb-dev/cachified/actions?query=workflow%3Arelease
[license-badge]: https://img.shields.io/badge/license-MIT%20License-blue.svg?style=flat-square
[license]: https://github.com/epicweb-dev/cachified/blob/main/LICENSE
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://kentcdodds.com/conduct